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What Is Editor/Assembler^Plus? 

Editor/Assembier-Plus (EDTASM-PLOS) is a software package, 
supplied on cassette tape, that includes a complete Editor, Macro 
Assembler, and Debug program. The Editor and Assembler include 
Radio Shack's EDTASM commands as a subset, but add many power- 
ful features to the basic capability of that package. The Debug 
package, called Z-BCJG, is a completely new design of a "big-system" 
debugger. 

EDTASM-PLUS is designed to be used on a TRS-80 Model I Computer 
with Level II BASIC and 16K or more of RAM memory. 

EDT ASM-PLUS gives you the capability to assemble TRS-80 assembly 
language programs directly into memory, without having to write out 
object programs to cassette tape and then load them.' In addition, 
EDTASM-PLCJS provides a macro capability to automatically 
generate in-line code by invoking an assembly-language macro, or set 
of predefined instructions. 

As the Editor, Assembler, and Z-BCJG are all resident at one time, it 
is a simple matter to efficiently edit source programs, assemble them 
into RAM memory, and then debug them. This process can be 
repeated over and over until the assembly-language program is check- 
ed out; the time required to switch between Editor and Assembler, 
between Assembler and Z-BUG, and from Z-BUG to Editor is a frac- 
tion of a second. 

The Editor portion of EDTASM-PLCJS includes the basic commands of 
EDTASM, but adds such features as line number offsets, new line 
range specifications, a block edit, moves and copies of blocks, string 
find and substitution commands, automatic line extension, and the 
ability to "quash" portions of EDTASM-PLUS to obtain additional text 
buffer area. 

The Z-BUG debugger of EDTASM-PLUS provides functions normally 
only found in larger computer systems, including symbolic debug- 
ging based on the assembler symbol table, byte, word, mnemonic, 
and ASCII formats, up to eight breakpoints, user-defined number 
bases, and single instruction stepping. 

The people at Microsoft hope you will be pleased with these new tools 
to facilitate your assembly-language programming of the TRS-80. 
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The Designers 



Microsoft Editor/Assembler-Plus was written by Mark L. Chamberlin 
and Wiiliam E. Yates, consultants to Microsoft. Mr. Chamberlin is the 
author of the original Radio Shack Editor/Assembler. 



A Word About Microsoft 

Microsoft produces high-quality, concise software for today's 
microprocessors. 

Microsoft's BASIC Interpreter, in its several versions, has become the 
standard high-level programming language used in microcomputers. In 
addition to Radio Shack TRS-80 Level II BASIC, and TRS-80 Disk 
BASIC, Microsoft has supplied BASIC Interpreters for the Commodore 
PET, the Apple II Computer, NCR 7200, Compucolor II, OSI, Pertec 
Altair, and many others. 

Microsoft's careful approach to the development of microprocessor 
software has allowed the production of large amounts of bug-free, well- 
designed code in a minimum amount of time. Currently available: 
BASIC interpreters for the 8080, 6800, and 6502 microprocessors; a 
FORTRAN compiler, assembler, loader and runtime library package for 
the 8080, and Z-80 microprocessors; an ANS-74 COBOL compiler for 
the 8080 and Z-80; and a complete offering of systems software for the 
new 16-bit microprocessors. 

Microsoft Consumer Products was founded as a division of Microsoft 
in the summer of 1979 to provide microcomputer users with high quali- 
ty system and utility software as well as application software. 

EDT ASM-PLUS is just one of many Microsoft products being planned 
for the end-user or consumer market. All of these software packages 
will be marketed by Microsoft Consumer Products. 

Microsoft Consumer Products is dedicated to providing only the best, 
most reliable microcomputer software. 

For more information on Microsoft Consumer Products software, please 
write to: __ 

/HKTADSOfT 

V CONSUMER^ PRODUCTS P 

400 108th Ave. N.E., Suite 200 
Believue, WA 98004 
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The Right Hardware 

EDTASM-PLUS can be used with the Radio Shack TRS-80 Model I 
Microcomputer with Level II BASIC and 16K RAM minimum memory. 

EDTASM-PLOS Cassette 

The EDTASM-PLUS Cassette that comes in your EDTASM-PLUS 
package is a high quality recording from Microsoft. 

The EDTASM-PLUS program is recorded two times on the side of the 
cassette tape with EDITOR/ASSEMBLER-PLUS printed on it. A length 
of leader tape precedes each recording. If you listen to the tape, you will 
hear a steady pilot tone during these leader sections. 

Side Two of the cassette tape contains two recordings of Stand-Alone 
Z-BUG. Instructions for the use of Stand-Alone Z-BUG are given in 
Chapter 5. 
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How to Load EDTASM-PLCIS 

To load EDTASM-PLUS from cassette, use the following instructions: 

1. Put the EDTASM-PLUS cassette into the TRS-80 recorder so 
that the side with Editor/Assembler-Plus is facing up. 

2. Rewind the tape to its beginning. 



3. Enter the command, SYSTEM, and press the 1 ENTER 1 key. 



4. In response to the * ? prompt, enter: EDTASM 1 ENTER | . 

5. Press the PLAY button on the TRS-80 recorder. There should 
soon be two asterisks in the upper-right corner of the TRS-80 
screen (the one on the right "blinks"). These two asterisks signify 
that EDTASM-PLUS is loading. 

6. A successful load will resu lt in ano ther *? prompt. In response 
to this prompt, enter: [7J 1 ENTER 1 . 

7. Assuming that all goes well, the screen will display a 
MICROSOFT COPYRIGHT notice, followed by an asterisk prompt 
character: * 



WARNING: 

Before loading EDTASM-PLUS or any other recordings into the TRS-80 
microcomputer, we strongly urge you to disconnect the smallest gray 
plug that is normally inserted into the "MIC" jack of the tape recorder. 

If for any reason during the actual reading of a tape the TRS-80 turns off 
the recorder (via the smallest gray plug), a "spike" may be recorded on 
the tape. Should this happen, the recording you are entering will be per- 
manently damaged. 

Our experience shows that this is most likely to occur when using the 
Radio Shack CTR-80 recorder, but we recommend that you still discon- 
nect the smallest gray plug no matter what recorder you are using. 
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What To Do About Loading Problems 

The TRS-80 is known to be "volume sensitive" when it comes to 
loading programs from cassette. 

The most common loading problem is finding the correct settings 
for the TONE and VOLUME controls on the TRS-80 recorder. We sug- 
gest that you start with a low VOLUME setting and adjust it up one 
half level each time you attempt a load. The TONE control is not as 
important, but change it also. 

Since the sensitivity of individual cassette recorders varies significant- 
ly, there is no way to determine specific settings. Once a tape loads, it 
is a good idea to write down the settings on the cassette label for 
future reference. 

If you still cannot load a tape, you might try cleaning and demagnetiz- 
ing the head of your TRS-80 recorder. Use a high-quality head cleaner 
and an inexpensive head demagnetizer for these tasks. Both can be 
purchased at Radio Shack or many other electronics outlets for under 
$10 (at the time of this writing). We don't recommend so-called 
"cleaner tapes" as they are often abrasive and may damage the head 
of your recorder. 

Other suggestions to try before taking the matter up with your Radio 
Shack dealer include the following: 

1. Try loading the second recording on your EDTASM-PLUS 
cassette. 

2. Try loading the tape with a different cassette recorder. 

3. Dust and other particles can sometimes prevent a load. To 
remove particles, run the tape through REWIND and FAST 
FORWARD a few times. 

4. Don't try loading the TRS-80 when you first turn it on. Let it 
warm up a few minutes instead. 

5. Remove the earphone jack and run the tape to listen for the 
leader tones and digital signals of the files. If you don't hear 
these sounds, try a different recorder. If you still don't hear 
them, chances are you have a blank tape. 
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Ask your Radio Shack dealer about Radio Shack's "cassette 
modification" fix. This hardware correction should make your 
EDTASM-PLUS less dependent upon exact VOLUME settings. 



EDTASM-PLOS 

Line Input and Output 

EDTASM-PLUS uses a backspace to delete the previous 
character just as is done in other TRS-8 progra ms. The entire input 
line may also be deleted by means of a 1 SHIFT | left arrow Q . 



Portions of E DTASM- PLOS use an 
is entered by a 1 SHIFT 1 up arrow \J\ 



"ESCAPE" character, which 
and displayed as a "$". The 



ESCAPE character cannot be deleted by a backspace or line deletion 
in Z-BUG. 



Tne 1 SHIFT I \@\ command will "h old" t he display during rapid 
listing of lines. Hitting any key except | break] will restart the display. 

The [BREAK 1 key can generally be used to return to the EDTASM- 
PLUS "command" level at any point during the middle of line input or 
after the messages "READY PRINTER" or "READY CASSETTE". This is a 
means to effectively cancel the current line or action. 
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RESET Recovery Procedure 

Cinder certain conditions control over EDTASM-PLOS may be 
lost. This is a (relatively) common occurrence during user program 
debugging when the user has not anticipated all of his program's ac- 
tions. EDTASM-PLUS may also infrequently "hang" during line printer 
or cassette I/O due to hardware malfunctions. 



To regain control at any time, press | break 1 . If [ break 1 does 
not return control to ESTASM-PLUS, use the following procedure: 



1. 



If 



using a system with no expansion interface, 



1 RESET 1 on the left rear of the cpu. If using a system with an 
expansion interface, press | RESET | «'^~ k^m; — ^«„,« 

&REAK L 



press 
ith an 

while holding down 



2. Enter | ENTER [ for "MEMORY SIZE?" if your system has an ex- 
pansion interface. 

3. Enter SYSTEM mode by inputting "SYSTEM" in response to 
the LEVEL II BASIC " > " prompt. 

4. Enter one of the following addresses to reenter EDTASM- 
PLUS: 

a . /17280 restarts EDTASM-PLUS and destroys the con- 
tents of the edit buffer. 

b . /17283 restarts EDTASM-PLUS with the contents of the 
edit buffer preserved. 

c . /17286 restarts EDTASM-PLUS with Z-BUG breakpoints 
and the contents of the edit buffer preserved. 

Bear in mind that if control was lost during debugging, portions of 
EDTASM-PLUS and/or the user program may have been destroyed 
and further use of EDTASM-PLUS without reloading may cause un- 
predictable results! 
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Chapter Two 
EDTASM-PLUS Editor 

• A Review of the Basic Editor Commands 

• A Review of the Editor Subcommands 

• A New Way To Specify Ranges of Lines 
Specifying Line Number Offsets 

• A Way To Edit a Set of Lines 
Without Individual E Commands 

• How To Move and Copy Blocks of Lines 

• Finding Strings and Substituting a New 
String for an Old 

• Automatic Extend (X) Subcommands 
Over a Range 

• Using the Quash Command To Obtain 
More Memory for Edits 

• Editor Error Messages 
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A Review of the 

Basic Editor Commands 

The Editor portion of EDTASM-PLOS adds many new and powerful 
commands to the basic Editor commands. Lets review the basic 
Editor operation and commands, and then discuss the additional 
capabilities. 

The Editor builds a buffer of text data in RAM memory. Usually this 
text data represents assembly-language source lines, although it can 
be any text data. Each source line is made up of four segments, or 
fields. The first field is the optional label field, the second is the Z-80 
instruction operation code or pseudo-operation code, the third is the 
operands for the operation, and the fourth field is the optional 
remarks for the instruction. The typical assembly source line 



START LD 



A,23 ;LOAD THE A REGISTER WITH 23 



has a label of "START", an operation code of "LD", operands of "A" 
and "23", and remarks starting with ";LOAD". Note that the remarks 
field is always started by a semicolon (";"). 

The Editor commands are used to read or write a source file from 
cassette tape, to insert or delete source code lines in the edit buffer, to 
replace source code lines with new lines, to display lines in the text 
buffer on the video display or to print them on the system line printer, 
to find a given character string in the text buffer, and to position the 
cursor to the proper line and tab position along the line. 

Let's construct a short source file and write it to cassette to show how 
the commands are used. Load EDTASM-PLGS as described in the first 
chapter. After a successful load, the title should be displayed, followed 
by the " * " prompt character. 

A two-line source file can be created in the text buffer by using the 
l(nsert) command: 



A,23 ;LOAD THE A REGISTER WITH 23 
START ;START ADDRESS FOR LOADER 



* 1100,10 




00100 START 


LD 


00110 


END 


00120 


(press 



break] ) 

The "100" in the I(nsert) command is the starting line number for the 
insert, while the "10" is the number of lines to increment for each new 
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line. Both the starting line number and increment are optional; the 
default starting line is 100 and the default increment is 10 on in- 
itialization, or the current line and last entered increment after use. 
Mow the source file of two lines may be written to cassette by the 
W(rite) command: 



*WTWOLN 
READY CASSETTE 



(hit any key except | BREAK] ) 



The source file from the edit buffer will be written out to cassette tape 
under the name "TWOLN". The name, by the way, is optional. If a 
name is not specified, no name will be used. If a name is used it may 
be 1 to 6 alphanumeric characters, starting with an alphabetic 
character. 

The cassette file can now be read back into the edit buffer by the 
L(oad) command, after first deleting the two lines by the D(elete) com- 
mand. 



*D100:110 
* L TWOLN 
READY CASSETTE 
* 



(delete the two lines) 
(load the source file) 



(hit any key except | BREAK | 



The L command does not require a file name. If none is given, the 
next file on the. cassette is loaded. Notice that a range of lines was 
specified by the colon (":") between the starting and ending line 
numbers for the delete. 

To verify that the file has been loaded properly from cassette, we can 
display the edit buffer by the P(rint) command: 

* p &* (display the buffer) 

The special symbols "#" and "*" represent the first line of the edit 
buffer and the last line of the edit buffer, respectively. We can use 
these symbols rather than having to remember the actual line 
numbers. 

If our system has a line printer, the contents of the edit buffer may be 
printed by the H command 

* H#: * ( print buffer on ' ine printer) 
READY PRINTER (hit any key except [ BREAK] ) 
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A variation on the H command allows only the text of the edit 
buffer to be printed— no line numbers are output: 

*T#:* (print text only) 

To insert additional lines between two existing lines, another insert 
command may be performed. To insert the line 

LD (3E20H),A ;STORE IN CENTER OF SCREEN 
between lines 100 and 110, for example, the l(nsert) below could be 
done 



* 1105 

00105 LD (3E20H),A 

NO ROOM BETWEEN LINES 



;STORE IN CENTER OF SCREEN 



The Editor assumed the increment value was 10 as it was not 
specified, accepted the first line, and then gave an error message 
when the next line, 115, would not fit in between lines 105 and 110. 
There comes a time in every programmer's life when all the lines be- 
tween lines 100 and 110 have been used. As the Editor does not use 
fractional line numbers, the source lines in the edit buffer must be 
renumbered by the N(umber) command: 



LOAD THE A REGISTER WITH 23 
STORE IN CENTER OF SCREEN 
;START ADDRESS FOR LOADER 



In this example, the renumber command was used to renumber the 
three lines with a starting line number of 100 and an increment of 10. 

The N(umber) line command is also handy when two or more edit 
files are L(oaded) into the edit buffer. The Editor does not "interlace" 
the lines by line number, but appends each successive file. The N 
command will automatically renumber the entire edit buffer properly 
in such a case. 

The R(eplace) command is used to replace one line with another line 
or group of lines. We can replace the first line by another, for exam- 
ple, in the sequence: 



*N100,10 






*P#:# 






00100 START 


LD 


A,23 


00110 


LD 


(3E20H),A 


00120 


END 


START 


* 
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*R100,10 

00100 START LD A.41H 

NO ROOM BETWEEN LINES 

* 



;LOAD A WITH ASCII 'A' 



Here again, if the Editor "runs out of room" between lines, it will res- 
pond with the "NO ROOM..." message. We could have replaced line 
100 with up to nine lines by: 
*R100,1 

00100 

00101 



Positioning commands enable us to find text within the edit buffer. 
The Editor maintains a pointer to the current edit line of the edit buf- 
fer. When the symbol "#" is specified, the Editor line pointer is set to 
the first line of the edit buffer. Specifying "*" sets the Editor line 
pointer to the last line of the edit buffer. We've seen how these sym- 
bols are used when we printed the entire edit buffer by the P#:* com- 
mand. 

A third symbol, the period, ".", refers to the current line in the edit 
buffer. We can scroll up and down the entire edit buffer by using the 
U P E and down [J] arrows. Once positioned to the proper line, we 
can use the "." symbol to reference the current line as in the print 
command 

which displays the current edit buffer line on the screen. 

Another way of positioning the Editor line pointer is by F(inding) a 
known character string in the edit buffer. The character string we 
would typically search for would be a unique string, if a label for a line 
of our source code was called by a unique name such as "TST34", for 
example, we could perform the following command to find the line: 



;TEST FOR A LESS THAN 50 
TEST FOR A LESS THAN 50 



* F$TST34 




00550 TST34 


CP 50 


*P. 




00550 TST34 


CP 50 
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The "$" in the command F$TST34 is not a dollar sign 

character! It is used to repre sent an "ESCAPE" character, which in 
the TRS-80 is equivalent to a | SHIFT | , up arrow [T] - It is used here 
as a "delimiter" (see "Finding Strings..." later in this chapter). 

The line in which the character string appears is printed out with its 
number. Displaying the current line (".") by a P. would again print the 
line. If the string is not found, the message "STRING NOT FOUND" is 
displayed. 

Notice that we must be aware of the position of the current line in the 
edit buffer. The search for the F command goes forward, so it is best 
to scroll back by using the up arrow [J] or to perform a P# to posi- 
tion the line pointer before the expected position of the search string 
or at the very top of the edit buffer. 

The search string in the F command may be any 1 to 16 character 
string that appears somewhere in the edit buffer. If the string appears 
more than one time in the edit buffer, the F(ind) command may still 
be used; the Editor will display the next occurrence of the string. 

Ail of the above Edit commands allow us to add, replace, delete, 
display, print, renumber, or otherwise manipulate edit buffer lines. In 
the next section we'll review how a line may be edited on a character 
by character basis. 

The Editor commands for line manipulation are shown below. These 
commands do not include the new EDT ASM-PLUS commands and 
features that we will be discussing later in the chapter. 

Command Format Sample 

Basic B * B Return to Level II BASIC 

Delete D[line1 [:line2]] *D100:* Deletes line 100 through 

end of buffer 

Find F$[string] *F$RALPH Fi nds strin g "RALPH". ("$" 

is | SHIFT 1 \J\ ) 

Insert l[line1 [,inc]] # 1109,3 Insert following lines start- 

ing at line 109 and in- 
crementing by 3 
(112,115,...) 
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Command Format Sample 

Hardcopy H[line1 [:line2]] *H#:221 Output lines from start of 

buffer through 221 to 
printer 

Load L[ ^filename] *L TEST Load file "TEST" from 

cassette tape 

Number N[line[,inc]] *N100,5 Renumber lines starting at 

line 100 and incrementing 
by 5(105,110,...) 

Print p *P Display the next 16 lines 

Print P[line1 [:line2]] *P100;123 Display lines 100 through 

123 

Replace Rfline [,inc]] * R300,3 Replace line 300 with follow- 
ing lines 

Type T[line1 [:Iine2]] *T#:* Print only text on system 

line printer 

Write Wfbfilename] *W JOHN Write edit buffer to 

cassette tape with name 
"JOHN" 

LiJ lQ Scroll up jj] or down 

is 

Notes: 

1. Brackets indicate optional arguments and \t> indicates 
optional blanks. 

2. "Line" defaults to current line if none entered. 

3. "Inc" defaults to last entered increment if none entered. 
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A Review of the 
Editor Subcommands 

The Editor subcommands are commands that allow characters within 
an edit buffer line to be edited on a character by character basis. Of 
course, a line could simply be edited by deletion and insertion using the 
Editor commands, but if only a portion of a line is to be edited, then the 
subcommands are much more efficient. 

The subcommand mode is entered by the Editor command "E". To edit 
line number 552, for example, the command entry would be: 

*E552 
00552 _ 

[Notice that after the command is entered, the line number of the line to 

be edited is displayed and the cursor positioned on the first character 

position of the line, ready for the first subcommand. 

If you have Level II BASIC you will see that the Editor subcommands are 

identical to those in the Edit mode of Level II BASIC. 

We will use a well known programming axiom to illustrate 

subcommand use: 

00522 _ 



The underline marks the cursor position, and the shaded area denotes 
the portion of the line that is not displayed, but in the buffer. 



We can position the c ursor along the line by the I SPACE BAR] and by 
the left arrow Q . The 1 SPACE BAR ] moves the cursor to the right, and 
the left arrow moves the cursor to the left. If a number precedes the 
space or left arrow, then the cursor moves that number of spaces to the 
right or left. Entering 20 followed by [SPACE BAR [ , for example, 
displays 

00522 PROGRAMS TEND TO OCC_ 

Entering 3 followed by a left arrow Q then displays 
00522 PROGRAMS TEND TO ___ 

Once the cursor is positioned we can delete, modify, or insert characters 
in the same manner we performed these operations on lines. 
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To insert characters, the "I" subcommand is used. The cursor is posi- 
tioned on the character of the line before the point at which new 
characters are to be inserted. Then the I command is entered, followed 
by the character s to be inserted. When all the characte rs desire d have 
been entered, a | SHIFT | up arrow [J] is entered. The [ SHIFT [ [jQ is 
used to tell the editor that we wish to escape from the edit mode sub- 
command. This special character is necessary because the insert ac- 
cepts all normal characters as characters to be inserted. 



Tne 1 SHIFT 1 \J] may be used at any time to end the insert and 
other edit modes. 

To see how the I subcommand works, let's add a word before "MORE" 
in our axiom. First position the cursor: 

00522 PROGRAMS TEND TO OCCUPY^. 



Now, type I, followed by "I6MCICH" followed by [sHiFTl [JJ 
00522 PROGRAMS TEND TO OCCUPY MUChL 



Deletions are performed by positioning the cursor on the character to 
be deleted and entering "D". If more than one character is to be deleted, 
a value can be entered before the D. To delete "MUCH", position the 
cursor on the M of MUCH, enter 5D, and the string will be deleted. 

00522 PROGRAMS TEND TO OCCUPY _ 



The format for C(hange) is similar to that for deletions. If the C is 
preceded by a value, then the specified number of characters are to be 
replaced by a string that follows the "C". If no value is used, then only 
one character is specified for the change. 

To change "MORE" to "LESS" in the sample axiom, enter 4CLESS after 
positioning the cursor under the "M" in "MORE". The result will be: 

00522 PROGRAMS TEND TO OCCUPY LESS_ 



The S(earch) subcommand allows us to find a specified character in 
our test line. For example, we could search for the "Y" by entering "SY" 
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while we were in the Edit mode. If the cursor were positioned 
somewhere before the "Y", the S subcommand would result in: 

00522 PROGRAMS TEND TO OCCUP_„ 

If a value was used before the S, the nth occurrence of the specified 
character would be found. If we were at the beginning of the line and 
"3SE" was entered, for example, the result would be: 

00522 PROGRAMS TEND TO OCCUPY MORE M_ 

Two other positioning commands are L and X. The L subcommand is 
used to print the entire line and then position the cursor at the begin- 
ning of the line. This is useful to see the remainder of the line at any 
time: 



00522 PROGRAMS TEND TO OCCUP„_ 



00522 PROGRAMS TEND TO OCCUPY MORE MEMORY THAN 

AVAILABLE. 

00522 __ 



IS 



The X subcommand does somewhat the same thing, in that it displays 
the entire line, but it then positions the cursor to the end of the line and 
sets the insert mode. This is useful for adding to the end of the line: 

00522 PROGRAMS TEND TO OCCUPY MORE MEMORY THAN IS 
AVAILABLE.^. 

Two somewhat violent commands, H(ack) and K(ill), allow the user 
to delete a segment of a line. The H subcommand hacks off the re- 
mainder of the line from the current cursor position and sets the insert 
mode. Hacking here: 

00522 PROGRAMS TEND TO OCCUP_ 



causes the following result, with the insert mode active: 

00522 PROGRAMS TEND TO OCCUP_ 

K deletes a segment of a line up to the nth occurrence of a specified 
character. The nth occurrence of the character is found as in the S sub- 
command. If the cursor is at the start of the line and "2KM" is entered, 
the following line results: 
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00522 __ 

There are a number of subcommands to restart or terminate the Edit 
mode. If a mistake is made while editing a line and the user wishes to 
cancel all previous editing changes, the A(gain) subcommand can be 
given to restart the edit with the cursor positioned at the beginning of 
the line as in: 

00522 PROGRAMS TEND TO OCCUPY MORE MEMORY THAN 
00522 __ 



If the line was mistakenly edited and the user wishes to simply restore 
the old line, then a Q(uit) can be entered to ignore changes. 
If all of the changes have been made correctly, then an E(nd edit) or 
simply the [ENTER | key can be used to enter the editing changes. 

00522 PROGRAMS TEND TO OCCUPY MORE MEMORY AND TIME 
THAN AVAILABLE. 



The subcommands for the Edit mode are shown below. 



Subcommand 

Again 

Backspace 

Change 

Delete 
End edit 

End edit 
Extend line 



Format 

A 

n*«— 

nCstring 



nD 



I ENTER 



Description 

Cancel all changes and restart 

Move cursor n positions left 

Change n characters at current 
cursor position to string 
characters 

Delete n characters at current 
cursor position 

End edit and enter all changes 
without displaying remainder of 
line 

End edit and enter all changes 
and display remainder of line 

Move to the end of the line and 
enter insert mode 
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Subcommand 


Format 


Description 


Hack 


H 


Delete line from current cursor 
position to end and enter insert 
mode 


Insert 


Istring 


Enter insert mode before current 
cursor position. Terminate with 
SHIFT | , up arrow [f] . 



Kill 

List line 
Quit 
Search 
Space 



nKs Kill all characters from current 

cursor position to nth occurrence 
of "s" 

L List line and position cursor to 

start of line in following line 

Q Quit Edit mode and ignore ail 

changes 

nSs Search for the nth occurrence of 

"s" 

nspace Move cursor n positions right. 
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A New Way To 
Specify Ranges of Lines 

EDTASM-PLOS extends the way that line number ranges can be 
specified. In the previous version of EDTASM, a colon was used when 
a range of lines was specified, as in * P100:300 which displayed all lines 
from 100 through 300. This method of specifying lines is still valid, but 
is supplemented by the ability to express a range by a starting number 
and the total number of lines in the range. 

Using this specification, it is easy to get "the first five lines of the edit 
buffer" or the "next six lines following line 1001". This is especially han- 
dy when all of the line numbers are not known, as in a recently edited 
source program. 

The format for this method of specification is 
SLN!n 

SLN is the "starting line number" and may be any valid line number for 
a line in the edit buffer. "!" is a symbol that designates that a line count 
rather than an ending line number will be used, "n" is the line count — 
the number of lines, including the starting line number, that are to be 
used in the range. 

To display the first five lines of the edit buffer, for instance, we can enter 
*P#!5 

To delete the 10 lines in the edit buffer starting with line number 101 1, 
we enter 

*D1011!10 

Of course, just as in the case of the "starting linerending line" specifica- 
tion, the range of lines must be in the edit buffer or a "BAD LINE 
NUMBER" error will result. If the range of lines is partially in the edit buf- 
fer, or if the starting line number does not exist, then the Editor works 
on all the lines within the range it can find, as one would expect. 
The "for how many lines" specification may be used in place of 
the "starting Sine numhenending line number" specification for 
any Edit command. 
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Specifying Line Number Offsets 

EDTASM-PLCIS provides a way to reference lines by offsets 

from a given line number. This feature makes it possible to reference 
the "line five lines above line 1770" or the "line 15 lines after line 
2022". Here again, as in the case of the "how many lines" specifica- 
tion, lines can be referenced without knowing all the line numbers in a 
set of lines. 

This type of line reference is very handy in positioning the Edit line 
pointer prior to searches, displays or prints. For example, if we want 
to start a search 5 lines back from the current line we could enter the 
following sequence: 

00550 THIS IS LINE 550 DISPLAYED BY THE P.-5 COMMAND. 

* F$LOST CHORD 

00580 THIS IS THE LOST CHORD LINE. 

* 
The first command displays the current line less five lines and posi- 
tions the Editor line pointer in preparation for the search. The F com- 
mand searches for the LOST CHORD and displays the line when it is 
found. 

The offset method of specifying line numbers can be used any 
time that a line number is called for. It can not only be used with 
the symbol for current line ("."), but also with the symbol for start of 
buffer ("#") and the symbol for end of buffer ("* "). To print the last six 
lines in the edit buffer, for instance, we could enter 

#P#-5:* 
and to print the first six lines at the beginning of the buffer we could 
enter 

*P#;# + 5 
Another format, of course, is to use the offset with an actual line 
number as in 

*P1010 + 5 

Of course if the resulting line number is nonexistent, as in the expres- 
sion #-2 or * +3, a "BAD LINE NUMBER" error message results. 
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A Way To Edit a Set of Lines 
Without Individual E Commands 

EDTASM-PLCIS adds a new way of using the E command, if 

there is a set of lines that requires editing, then a collective E(dit) 

command can be given to remain in the Edit mode for the entire 
range rather than entering an E for each line. 

This is a feature that makes editing go much more smoothly when 
more than one line is to be edited. Suppose that lines 1010 through 
1050 need to be edited. Using the collective edit command we simply 
say 

E1010:1050 or E1010;1010 + 4 or E1010I5 
The Editor will now stay in the Edit mode until lines 1010 through 
1050 have been edited and will then return to the command driver. 
If you've made a mistake and really don't want to remai n through the 
entire range, simply type a Q to quit the Edit mode. The j ENTER 1 and 
E subcommands are used as before to enter the line after editing. 
The new format for E, then, is used with any range specification when 
a set of contiguous lines is to be edited, and is not used when just 
one line is to be edited as before. 



How To Move and Copy 
Blocks of Lines 

Two new commands have been added to EDTASM-PLCIS to 
enable the user to move a block (or range) of lines or to copy a 
block of lines. 

The move command allows us to take a specified block of lines and 
move them to a new area of the edit buffer. The old block of lines is 
deleted. Previously, this action would have been accomplished by in- 
serting the lines in the new area and then deleting the old lines. The 
M(ove) command is a powerful feature as it allows us to rearrange sec- 
tions of assembly-language programs easily. 

The format of the move command is 



MTLN,RNG,INC 



(increment optional) 
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TLN" is the "target" line number, the starting line number for the new 
block. "RNG" is the specification for the old block of lines; RNG can 
use any of the range specifications that we have mentioned previous- 
ly, as, for example, 100:200, 100:100 + 5, or 10015. "INC" is the incre- 
ment for line numbering on the new block. 

As an example, suppose that we want to make a subroutine out of 
some assembly language code to shift the HL register pair four bit 
positions left. The initial code is: 



#>500:500 + 3 








00500 SHIFT 


ADD 


HL,HL 


;SHIFT HL 1 BIT LEFT 


00510 


ADD 


HL,HL 


;SHIFT HL 2 BITS LEFT 


00520 


ADD 


HL,HL 


;SHlFT HL 3 BITS LEFT 


00530 
* 


ADD 


HL,HL 


;SHIFT HL 4 BITS LEFT 



This code is "imbedded" in other code, and we would like to move it 
to a common subroutine area at the end of all other code. We can 
easily move the code to a new area starting with line 10000 by: 

*M10000,500!4,10 
This move transfers lines 500 through 530 (500!4) into a new block of 
lines 10000 through 10030. The target line number was 10000, and 
the increment for the new block was 10. The old lines 500 through 
530 were deleted after the move. 

About the only thing to watch for in the move is that the new range of 
lines does not conflict with existing lines in the edit buffer. If there is a 
previous line number which is the same number as the starting line 
number in the move command, the Editor will attempt to make the 
move by starting at the starting line number plus the increment. If line 
number 10000 already was used in the previous example, the new 
block would start at 10010. 

If there is not enough room to add all of the lines in the move, a "NO 
ROOM BETWEEN LINES" error will result. This would have happened in 
the previous example if line 10030 had been in use, for instance. 
The copy command is similar in format and concept to the move. 
The only difference between the move and C(opy) commands is that 
move deletes the old block of lines, but copy keeps them intact. The 
format of the copy is: 
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CTLN,RNG,INC (increment optional) 

We could have copied the lines of the previous example by: 
*C1000u,500!4,1 

This command would have moved the four lines at 500 through 530 in- 
to the new block of 10000 through 10003, but retained the lines at 500 
through 530, assuming a previous (default) increment of 10. 

Just as in the move command, if there is not enough room to insert all 
of the lines in the new block, a "NOT ENOUGH ROOM" error results 
Likewise, the starting line number is changed to the target line plus the 
increment if the target line number already exists. 

"INC" defaults to the current increment if not specified, for both 
Move and Copy. 

Finding Strings and Substituting 
a New String for an Old 

We have already discussed the F(ind) command in our review of the 
basic Editor commands. EDTASM-PLCIS extends the usefulness 
of this command with its new methods of specifying ranges of lines 
Kecall that in the previous approach, the Editor line pointer must be 

PnrfcM nwio a Hne bef ° re the b,ock of iines to be searched. In 
tuiAbM-PLGS, a range of lines can be specified for the search. 

The format for this type of search is: 

FRNG$string 

"RNG" is a range specification in any of the formats we have been 
usl ng - 100:300, 100115, or 100:100 + 23, for example. (The strino 
to foe searched for is preceded by a "$" delimite r, which is not a 
dollar sign, hut an ESCAPE character, | sh ) ft [ Q] !) 
The benefit of this approach is that we do not have to first position the 
Editor line pointer; the search simply takes place over the specified 
range of lines. y 

When a range is specified for a search, all lines containing the 
search string are displayed. 
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Suppose that we have mistakenly used the mnemonic "LDDIR" instead 
of the correct assembler mnemonic "LDIR". We can find all occurrences 
of the error in the last 20 lines of the edit buffer as follows: 



F*-19:*$LDDIR 
02005 MOVE1 LDDIR 
02200 LDDIR 

02300 LDDIR 



;MOVE THE BLOCK 

MOVE THE BUFFER 

MOVE HEAVEN AND EARTH 



In the above code there were three lines that contained the character 
string "LDDIR". The three lines were displayed, and the Editor line 
pointer set to the last line to be displayed. 

The Substitute command works pretty much the same as the F(ind) 
command when a range is specified. If we had wanted to substitute a 
string of "LDIR" for the erroneous string "LDDIR" we could have used 
the same format to specify the search string, but appended a string to 
be substituted: 



*S*-19:*$LDDIR$LDIR 
RANGE * — 



SUBSTITUTE STRING 
SEARCH STRING 



The Editor would then have searched for the LDDIR string over 
the entire range and substituted the LDIR string at each occur- 
rence of LDDIR. In this case the lines containing the newly substituted 
strings are displayed: 



*S*-19:*$LDDIR$LDIR 
02005 MOVE1 LDIR 

02200 LDIR 

02300 LDIR 



;MOVE THE BLOCK 
;MOVE THE BUFFER 
MOVE HEAVEN AND EARTH 



In both the F(ind) and S(ubstitute) commands, the specified strings for 
the search and replacement strings must be 16 characters or less. If a 
substitute is performed and a new line results that is greater than 128 
characters, a "NEW LINE TOO LONG" message is displayed. This can 
happen, of course, if the original line is long to begin with, and the 
substitute string is longer than the search string. 
The Substitute) command can be used without a range, just as 
the F(ind) command can be used without a range of lines. In this case, 
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the Editor finds the first occurrence of the string, makes the substitution 
of the second string, and then displays the line. The line pointer is set to 
the line containing the string. The format in this case is: 

*S$string (where $ is the ESCAPE, [shfTI QJ ) 

The Find and Substitute commands may be used with a new range, but 
without a new string. In this case, the Editor simply uses the last entered 
string as a default string. 

The F and S commands may be used without a string(s) or range. In 

this case the Editor searches for the current string from the current line. 
The F and S commands are extremely powerful when used to find and 
correct erroneous mnemonics or operands in source code, an operation 
which is necessary far more frequently than assembly-language pro- 
grammers would hope for! 
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Automatic Extend (X) 
Subcommands Over a Range 

EDTASM-PLUS adds the capability of entering the extend (X) 

subcommand mode for a range of lines. One use for this feature is to 
add comments to lines of assembly-language source code. 

The format of the Extend command is 

XRNG (RNG usually specified but optional) 

where RNG is a range of lines, specified by any of the methods that we 
have described above, for example 100:1000, 333-45:300, or 1000112. 
If RNG is not specified, only the current line will be extended. After the 
range of lines has been entered, the Editor automatically enters the Edit 
mode for the first line, positions the cursor after the last character of the 
line, and sets the insert mode. Characters can then be added to the line 
(or other editing subcom mands ca n be performed). When all characters 
have been added, an E or [ enter] is input, and the Editor displays the 
next line of the range in the same fashion. This process is repeated over 
the entire range of lines that has been specified. 

Let us see how this command works. Suppose that we wish to add com- 
ments to lines 1000 through 1020. The sequence used follows: 

*X1000:1020 

01000 LD A,15__ 

(comment added to above line, followed by | ENTER] ) 
01010 LD HL,BUFFER_ 

(comment added to above line, followed by I ENTER | ) 
Q1020 LD B,40H 

(comment added to above line, followed by I ENTER | ) 

To get out of the a utomatic Extend mode at any time, simply enter a Q 
in place of the E or | ENTER | after changes have been made. Remember 
that a Q or E must be preceded by a I SHIFT ] \J\. 



36 



Osieg the Quash Command to 
Obtain More Memory for Edits 

During normal operation in EDTASM-PLUS, the Editor, Assembler, 
and Z-BUG are "resident" at the same time. These three segments of 
EDTASM-PLUS use 12.5K bytes of RAM memory and are arranged as 
shown in the figure below: 



LOW RAM 
MEMORY 



=* 7200H 



MACHINE I/O 



EDITOR 



ASSEMBLER 



Z-BUG 



EDIT BUFFER 



SYMBOL TABLE 



: VARIABLE 



I 



HIGH RAM USER 

MEMORY | RAM 
I * 

The edit buffer uses available RAM memory for text storage. If more 
space is required to hold text in the edit buffer, either the Z-BUG or 
Assembler and Z-BUG areas may be released to the system for an ex- 
tension to the edit buffer area. 

The command for this action is the Quash command. If only the 
Z-BUG portion of the system is to be used for the edit buffer, then the 
QZ 

command is entered. If both the Z-BUG and Assembler portions are 
to be used as edit buffer area, then 

QA 

is entered. 
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Quashing Z-BGG adds an additional 3.2K bytes for the edit buffer, while 
quashing both Z-BUG and the Assembler adds an additional 8. IK bytes 
for editing. 

The Quash command preserves the current text in the edit buffer 
so that it does not have to be reentered after the Quash. 

Because this is a catastrophic action if the command is erroneously 
entered, EDT ASM-PLUS asks the user "QUASH?" to mak e certain that 
he wants to quash. If the user has made a mistake, a [break] may 
be typed to abort the quash; hitting any other key causes the 
quash to take place. 

Of course once the Quash command has been acted upon, any 
Assembler or Z-BGG command will result in the error message "BAD 
COMMAND" if that function has indeed been quashed. QZ disables the Z 
command and QA disables the Z, A, Q, and O commands. 

The Quash command is meant to provide more space for general 
text editing or for situations where there are too many source lines to 
be held without quashing a portion of the package. Bear in mind that if 
the assembler is also quashed, it probably will not be possible to assem- 
ble a source program even by reloading as there will not be enough 
space in the edit buffer to accomplish the reload. The most practical ap- 
proach with the source programs is to quash only the Z-BUG portion, 
assemble the program, output the object to cassette tape, and then 
reload the object program with Stand-Alone Z-BUG for debugging. 

Use the quash capability only when absolutely necessary, as its 

use deletes many of the powerful assembly and debug features of 
EDT ASM-PLUS that we will be discussing shortly. 
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Editor Error Messages 



The following is a list of error messages that may occur durinq Editor 
operation: 

Description and Corrective Action 
Editor does not recognize command. Is it valid? 
Editor cannot find line number. Check to see if 
line is actually present in the edit buffer. 



Message 

BAD COMMAND 

BAD LINE NUMBER 



BAD PARAMETERS 



Editor cannot decode the operands for the com- 
mand. Check format. 

(Jser has specified operation on a line when buf- 
fer is empty. Reload or reenter text. 

No more room in the edit buffer. Quash Z-BGG 
or Z-BGG and Assembler to get more space, or 
break up program into separate modules. 

Substitute has been performed that resulted in a 
line greater than 128 characters. Shorten the 
line. 

NO ROOM BETWEEN Insert, move, or copy action resulted in too 
UNES man Y lines to fit between existing lines. 

Renumber existing lines with larger increment. 
STRING NOT FOUND Find or substitute command specified a string 

that cannot be found. Check the search string 

for proper characters. 



BUFFER EMPTY 



BUFFER FULL 



NEW LINE TOO 
LONG 
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Chapter Three 
EDTASM-PLCIS Assembler 

A Review of the Assembler Operation 
A Review of Pseudo-Operations 
Assembler Switches 

Assembling Into Memory -Automatic Origin 
Assembling Into Memory -Manual Origin 
Assembling With an Absolute Origin 
Assembler Expression Evaluation 
Conditional Assembly 
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A Review of the 
Assembler Operation 

EDT ASM-PLUS adds many new features to the basic assembling ability 
of the Editor/ Assembler. Before we discuss the new capabilities, let us 
review the basic assembly process, pseudo-operations, and assembly 
commands. 

The Assembler operates from source code stored in the edit buffer. 
The source code is generated from the keyboard, using the Editor, or is 
loaded from a previously written source file on cassette tape. 

The source code consists of source lines. Each line of source code 
generally produces one machine language instruction, although under 
certain conditions no instructions are generated, data is generated, or 
some other Assembler action takes place. 

The usual assembly-language source line consists of four fields: an op- 
tional label, an operation code, operands, and optional remarks: 



MERGE ADD 

-i r 

Label Operation 
Code 



HL,BC ;ADD DISPLACEMENT TO ADDRESS 



T 

Operands 



T 



Remarks 



The operation code is the heart of the assembly-language line. It 
is a mnemonic name that represents one of the hundreds of individual 
instructions that are in the instruction repertoire (or set) of the Z-80 
microprocessor used in the TRS-80. 

Each of the instructions found in the Z-80 has a predefined format, and 
a certain number of operands associated with its operation. Some in- 
structions require no operands, while others require two or three. 
Operands may be register names, data values in decimal or hex- 
adecimal, symbols, expressions, or combinations of these things. 

The remarks column is strictly optional. When used, the remarks field 
must start with a semi-colon (;) to delimit the remarks from other fields. 
The source line may also consist entirely of a remark with a starting 
semi-colon. 

The label column is another optional column. Labels are used in lieu 
of BASIC line numbers so that one instruction may reference another, 
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primarily for conditional and unconditional jumps. 

The fields of each source line are *f ree-form" fields, that is, they do not 
have to start at specific columns. Each field of the source line need only 
be separated by a blank, and the remarks field must have a semi-colon 
delimiter. For convenience and readability, however, the right arrow will 
tab to predefined tab positions, and the four fields can be put into nice, 
neat columns during Edit. 

Let us assemble a sample program to review how the Assembler 
operates. The source program below clears the display by storing 
blanks in all of the 1024 character positions. We will assume that the 
Editor has been used to produce this set of lines in the edit buffer. 



00100 




ORG 


7000H 




00110 CLEAR 


LD 


HL3C00H 


;ADDRESS OF SCREEN START 


00120 




LD 


BC,1024 


;COUNT OF POSITIONS 


00130 


LOOP 


LD 


A,20H 


;LOAD BU\NK 


00140 




LD 


(HL),A 


;STORE BUNK 


00150 




INC 


HL 


;BUMP POINTER 


00160 




DEC 


BC 


DECREMENT COUNT 


00170 




LD 


A,B 


TEST DONE 


00180 




OR 


C 


;MERGE LS BYTE 


00190 




JR 


NZ.LOOP 


;GO IF MORE TO STORE 


00200 




END 







The source code above represents the clear program in symbolic 
form. It cannot, of course, be loaded into the TRS-80 in this form for ex- 
ecution, but must first be translated from the symbolic source form 
above into machine language instructions that the Z-80 will recognize. 
Two labels have been used — "LOOP" and "CLEAR". Many times we do 
not know where each instruction will reside in memory and for that 
reason do not assign absolute memory addresses to the instructions. 
The symbolic location of the LD A,20H instruction is at LOOP and we 
have referenced that location in the "Jump Relative if Not Zero" instruc- 
tion, which will cause a jump to location LOOP 1023 times through the 
loop. 

One important point about the symbolic form of the program: We 
could, in, fact, sit down and laboriously hand assemble these instruc- 
tions into machine language form by reference to the Z-80 manual. The 
symbolic form, however, relieves us of this chore and lets the Assembler 
do ail of the calculations. 
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Entering the command "A" takes the contents of the edit buffer and 
translates the symbolic form of the program into machine code. 



7000 


00100 


ORG 


7000H 




7000 21003C 


00100 CLEAR 


LD 


HU3C00H 


ADDRESS OF SCREEN 
START 


7003 010004 


00120 


LD 


BC.1024 


COUNT OF POSITIONS 


7006 3E20 


00130 LOOP 


LD 


A,20H 


LOAD BU\NK 


7008 77 


00140 


LD 


(HL),A 


STORE BLANK 


7009 23 


00150 


INC 


HL 


BUMP POINTER 


700A0B 


00160 


DEC 


BC 


DECREMENT COUNT 


700B78 


00170 


LD 


A,B 


TEST DONE 


700C B1 


00180 


OR 


C 


MERGE LS BYTE 


700D 20F7 


00190 


JR 


NZ,LOOP 


GO IF MORE TO 
STORE 


0000 


00200 


END 






00000 TOTAL ERRORS 








CLEAR 


7000 








LOOP 


7006 









NOTE: Some lines which fit as one line on your 
computer screen will not fit on this manual page as 
one line. These lines have been continued on a se- 
cond line with the information continued beneath 
the last column. 

The assembly listing shown above consists of four parts. The 

right section is the "source line image," simply a repetition of the 
source code from the edit buffer. The third column from the left lists 
the corresponding source line number for each line of code. 

The two columns on the left are the locations at which the instructions 
will reside, and the actual machine language form of the instructions. 
By specifying the special assembler "pseudo-operation" ORG, for 
origin, we have informed the assembler to assemble the code starting 
at location 7000H, 1024 bytes down from the top of RAM in a 16K 
system. 

The machine language form of the instruction consists of one to four 
bytes of data. Each byte of data is represented by two hexadecimal 
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digits, so there may be from two to eight hex digits in the second col- 
umn for the corresponding instruction. The location column on the far 
left is incremented to reflect the number of bytes in the instruction. A 
two-byte instruction, for example, adds two to the address for the next 
instruction. 

The machine language code represented by the data in the second col- 
umn is the object code produced by the assembler. This object code 
may be saved on cassette tape for reloading by a debug package or by 
the monitor (SYSTEM) mode logic in Level II or Disk BASIC. Alter- 
natively, it may simply be kept in memory for on the spot debugging 
with Z-BGG. This in-memory assembly is not generally possible with 
assembler packages and is one of the powerful features of EDTASM- 
PLCIS we will be talking about shortly. 

A Review of 
Pseudo-Operations 

When is an opcode not an opcode? When it is a pseudo-operation! As 
we mentioned earlier, most source lines cause one machine-language 
instruction to be generated. The exception to this, however, is source 
lines that do not contain instruction opcode mnemonics, but contain 
operations to be performed by the assembler. These instructions are 
called pseudo-ops as they are written in the opcode column of the 
source line. 

We have seen two of the pseudo-ops in the sample program of this sec- 
tion, the END and ORG pseudo-ops. 

The END pseudo-op simply marks the end of the assembly source 
code. The Assembler makes several passes to resolve forward 
references and the like, and it must know where the end of the source 
code is. 

The END may have an argument that specifies the starting address 

for the program. This is used by both Level II BASIC SYSTEM mode and 
by the EDTASM-PLUS Z-BUG Load command as the default starting 
address. 

The ORG pseudo-op tells the Assembler where the program will 
be loaded for execution. It is generally the first command in the 
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source code. The ORG may also be used within the source code to in- 
dicate where sections of the program are to reside, or for reserving 
blocks of storage (see discussion of DEFS). 

The ORG is a necessity for the old version of EDTASM. In EDTASM- 
PLGS, however, although we may use ORG to assemble absolute 
programs, it is generally not necessary. (We will explain in detail later 
in this chapter.) 

There are four pseudo-ops that are used to generate data in place of 
machine-language instructions. Data values generated by these 
pseudo-ops are used as general constants, table values, or other types 
of data. 

The first of the four generates one byte of data at the current 
assembly location. The DEFine Byte below will create a single byte of 
100. 



01000 HUND 



DEFB 64H 



;GENERATE CONSTANT OF 100 



A second pseudo-op, DEFine Word, generates two bytes (16 bits) of 
data. This data is almost always address data, arranged least 
significant byte followed by most significant byte, in standard 
Z-80 address format. 



01001 LOCNT 


DEFW 


START 


;ADDRESS OF START 


01002 


DEFW 


LAST 


;ADDRESS OF LAST 


01003 


DEFW 


MID 


;ADDRESS OF IN BETWEEN 



The third pseudo-op, DEFB with a character operand in quotes, is 
much like the normal DEFB except that an ASCII character is 
generated. ASCII is the seven bit code (most significant bit is a zero) 
used by all TRS-80 input and output devices for character representa- 
tion. 

02010 DEFB 'S' ;GENERATE AN ASCII S 

A related pseudo-op, DEFine Message, generates a string of ASCII 
characters used as a message for output to the screen or printer. 

03020 MESSG1 DEFM 'I NEVER USED A PROGRAM I DIDNT LIKE' 

All of the pseudo-ops in the last group generated data which would 
be loaded along with machine language instructions. The DEFS 
pseudo-op, however, does not generate data, but simply tells the 
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assembler to reserve a block of storage locations. The DEFine 
Storage pseudo-op simply causes the Assembler location counter to 
be incremented by the number of bytes specified by the operand. 
When the object code is loaded, the loader bypasses the block defined 
in the DEFS, storing nothing there. This code shows the use of 
DEFS: 

7000C3CB70 03000 JP NEXT ;CONTINUE 

7003 03010 TABLE DEFS 200 ;RESERVE TABLE OF 200 

BYTES 
70CB 3E02 03020 NEXT LD A,2 ;TWO TIMES THROUGH 

NOTE: Some lines which fit as one line on your 
computer screen will not fit on this manual page as 
one line. These lines have been continued on a se- 
cond line with the information continued beneath 
the last column. 

Mote that in the object code above, the LD instruction was assigned a 
location CBH, or 200 decimal bytes past the first instruction at 7000H 
through 7002H. 

Another way of performing exactly the same action would be to use a 
second ORG pseudo-op to reset the assembler (and loader) location 
counter: 



7000 C3CB70 

7003 

70CB 



00110 

00120 TABLE 
00130 



JP 

EQU 

ORG 



70CB 3E02 00140 NEXT LD 



NEXT CONTINUE 

$ ;START OF TABLE 

$+200 ;RESERVE TABLE OF 200 

BYTES 
A,2 ;TWO Tl M ES TH ROUGH 



NOTE: Some lines which fit as one line on your 
computer screen will not fit on this manual page as 
one line. These lines have been continued on a se- 
cond line with the information continued beneath 
the last column. 

In the above code we used another pseudo-op, the EQCIate 
pseudo-op. This pseudo-op equated a label to the value of the current 
assembler location counter ("$"). As the assembler scans the source 
lines, it builds a table of symbols and associated values called the 
symbol table. 
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Many of the values in the symbol table are the locations of the names 
of instructions which are then filled in for jumps and other instructions 
as the numeric values. Other values equated with symbols, however, 
may represent different data. If we used the ASCII character for "turn 
on cursor" (14) many times in a program, we might choose to call it 
"ONCUR" by an EQU: 

02000 ONCUR EQU 14 ;TURN ON CURSOR CHARACTER 

Thereafter, every time we wanted to load, compare, or utilize the 
character, we could use "ONCUR" in place of 14 as in: 

04000 CP ONCUR ;TEST FOR 14 ON CURSOR CHAR 

When the operand of an EQUate is "$", then the label used in the 
EQCJ is equated to the current Assembler location counter value, 
which is simply the address for which the next instruction or data will 
be assembled. 

The last pseudo-op is DEFL. DEFL is used similarly to EQU, but the 
label used with DEFL may be redefined later in the source code. We 
could, for example, have: 

02000 COUNT DEFL 100 ;SET COUNT 



(other source code) 



04000 COUNT DEFL 200 ;SET COUNT 
Most of the pseudo-ops can use a general expression as an 
operand. 
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Assembler Switches 

The basic command to start assembly is "A". When this com 
mand is given, the Assembler will rapidly assemble the code in the 
source buffer and display it on the screen as it does so. At the end of 
the listing on the screen, the symbol table for the assembly will be 
listed in alphabetical order. 

The symbol table contains all user labels from the assembly. Each 
symbol is displayed along with the corresponding value for that sym- 
bol. In many cases this value represents the location of the symbol in 
the assembled program; in other cases the value is a result of an 
EQCJate. 

At the end of the listing of the assembly and symbol table, the 
Assembler is ready to output the object to cassette tape. The 
assembler asks "READY CASSETTE " so that the user can prepare the 
cassette. Hitting any key other than ^ ' ' ' 



I BREAK I or f SHIFT 



... ~, - - ■ ' — ■ — ■ i i^i after 

this prompt results in the object code of the assembly being output to 
cassette tape. 

If no file name is used, the object file will be output with file name 
"NONAME". If a name is used, the Assembler will use the name 
from the A command: 

* A m AM E ( % i s optional space) 

There are various options, called "switches", that may be used 
with the assembler "A" command. 

The output of object code can be disabled by the "/NO", No Object 
switch. Many times it is convenient to assemble on a trial basis before 
producing an object tape. Any assembly errors can then be corrected, 
and the object tape produced after all assembly errors have been dealt 
with. The format for this option is 

*A/NO 

The listing and/or symbol table output may be suppressed by the "NL" 
and "NS" switches. If a hardcopy of the listing is required, the "LP" 
switch causes the listing and symbol table output to be sent to the 
system line printer. An assembly with no symbol table printout, no 
object, and output to the line printer, for example, would be specified 
by: 
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* A/NO/LP/NS 
The switches may be used in any order. 

The "WE" switch causes the assembler to wait on errors. This switch is 
useful when the listing is being displayed on the screen, as the 
assembly is displayed so rapidly that the individual errors cannot be 
seen. Pressing any key except | BREAK [ or \c\ after the err or wait 
causes the Assembler to continue and wait on errors. Pressing [break | 
aborts the assembly. Pressing [c] continues the assembly without 
waiting on further errors. 

The above switches were used in the previous version of EDTASM. 
They are still valid in EDTASM-PLUS. EDTASM-PLGS adds additional 
assembly switches that are used in the same fashion. The new 
switches are "IM" to assemble directly into memory, "MO" for manual 
origin, and "AO" for absolute origin. We will discuss these in the next 
section of this chapter, as they all relate to assembling programs 
directly into memory. 

For reference, the Assembler switches are: 

Switch Description 

/NO Suppress object output 

/NS Suppress symbol table printout or display 

/NL Suppress listing printout or display 

/LP Output listing and symbol table to line printer 

/WE Wait on errors until key depressed 



/IM 

/MO 

/AO 



Assemble object code directly into memory 
Assemble with user-specified origin 
Assemble with absolute origin 



Assembling Into 
Memory-Automatic Origin 

EDTASM-PLGS adds a powerful new feature to the basic 
Editor/Assembler, the ability to assemble source programs direct- 
ly into memory. This "assemble into memory" capability lets the 
user avoid the time consuming portion of assemblies during debug- 
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ging — creating and loading an object tape. Furthermore, as the 
Z-BGG debugger is a part of EDTASM-PLGS, programs assembled in- 
to memory may be immediately debugged. 

A second important quality of assembling into memory is that the 
assembler will automatically relocate the object code to a convenient 
portion of memory; the user is relieved of the task of figuring out 
where he should place the object code. 

Typically, the assemble into memory feature can be used during the 
debugging phase of assembly-language program development. Once 
the program has been fully debugged, it can then be output in final 
form to cassette tape for subsequent loads by the SYSTEM command 
in BASIC. 

To see how this feature works, let us assemble a sample program. The 
command A/IM assembles the program from page 43 and produces 
the listing shown below: 



HAD 21003C 


00110 CLEAR 


LD 


HL.3C00H 


;ADDRESS OF 
SCREEN START 


71 BO 010004 


00120 


LD 


BC,1024 


;COUNT OF POSI- 
TIONS 


71 B3 3E20 


00130 LOOP 


LD 


A,20H 


;LOAD BLANK 


71 B5 77 


00140 


LD 


(HL),A 


;STORE BLANK 


71B6 23 


00150 


INC 


HL 


;BUMP POINTER 


71 B7 0B 


00160 


DEC 


BC 


;DECREMENT 
COUNT 


71B8 78 


00170 


LD 


A,B 


;TEST DONE 


71 B9 B1 


00180 


OR 


C 


;MERGE LS BYTE 


71BA20F7 


00190 


JR 


NZ,LOOP 


;GO IF MORE TO 
STORE 


0000 


00200 


END 






00000 TOTAL ERRORS 








CLEAR 71AD 










LOOP 71 B3 











NOTE: Some lines which fit as one line on your 
computer screen will not fit on this manual page as 
one line. These lines have been continued on a 
second line with the information continued beneath 
the last column. 
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One of the statements that we left out of the above assembly was the 
ORG, which specified the origin of the program. This was left out on 
purpose, as the Assembler automatically determines the origin for in 
memory assembly; it uses the first available memory location above 
the space used for EDTASM-PLUS, the Edit buffer, and the symbol 
table. 

We can see from the listing that this program was assembled starting 
at location 71ADH. (This location may vary depending upon the ver- 
sion of EDTASM-PLUS that you are using.) 

If we look back to the figure in Chapter 2, we can see how the 
assembler allocates memory for in memory assembly. The areas for 
machine I/O, Editor, Assembler, and Z-BCIG are fixed in size. The Edit 
buffer, of course, holds whatever source program we have entered and 
is therefore variable size. The symbol table is also variable size and 
depends on the number of symbols that we are using in our source 
program. Each symbol takes from 4 to 9 bytes, dependent upon the 
number of characters in the symbol. 

As the Assembler generates object code, it is built upward towards 
high memory from the symbol table end. The total area available for 
long assemblies ranges from the automatic origin to the end of RAM 
memory in the TRS-80. In a minimum system, this would be up to 
location 7FFFH; in a maximum system the upper limit would be 
FFFFH. 

ORG pseudo-ops should, in general, not be used when assembling 
into memory with an automatic origin. If they are used, the effective 
address of the ORG will be the ORG address plus the value of the 
automatic origin. If the automatic origin is 71ADH, for example, the 
pseudo-op 

ORG 200H 

produces an origin of 73ADH, which is probably meaningless unless 
the user plays special tricks to reference data or code to the start of 
the program. 
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Assembling Into 
Memory -Manual Origin 

It is possible for the user to specify a manual origin in EDTASM- 
PLUS. There are times when the user might like to determine the area 
of memory in which his program is to be assembled. The program, 
for example, might normally reside at 0C000H when it is loaded by the 
SYSTEM command in BASIC; it is convenient to be able to generate 
object code at this location so that the user can debug the actual loca- 
tions for the program. 

The O(rigin) command allows the user to specify this manual origin. 
Note that this is an EDTASM-PLUS command and not an assembler 
pseudo-operation. When the O command is entered, the Assembler- 
responds with the following message: 

*o 

FIRST = 7088 LAST = XFFE USRORG = XFFF USRORG = 

The meaning of these parameters is shown below. FIRST is the first 
location after the Edit buffer, which is the first location of the symbol 
table for the program in the Edit buffer. LAST is the last location that 
the system can use. This is one less than the maximum RAM memory 
location. USRORG is the user specified manual origin. Initially this is 
the last location in memory. 

A new USRORG may be specified by typing in a value between FIRST 
and LAST. When this is done, the user defines a User Ram Area into 
which he may assemble by the manual origin switch, MO. If an 

assembly into memory is then performed with a "/MO", the Assembler- 
will assemble the object code starting at the user origin. 

Suppose, for example, the user specifies a manual origin, or USRORG, 
of 8000H 

*o 

FIRST =7088 LAST = XFFE USRORG = XFFF USRORG = 8000 
If he then starts an assembly by: 

*A/IM/MO 

the object code will be assembled into memory starting at location 
8000H, and continuing upward from that location. 
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The default value for USRORG is the last available memory location. 
This value should be reentered if assemblies with automatic origins are 
to be done to provide maximum space for the symbol table and object 
code. For 16K RAM systems this value is 7FFF, for 32K systems BFFF, 
and for 48K systems FFFF. 

As in automatic origin assemblies, no ORG is necessary. ORGs present 
in source code result in an origin value of the ORG operand plus the 
USRORG value, which is generally meaningless. 



LOW RAM 
MEMORY 


I/O EDITOR, 

ASSEMBLER, 
Z-BUG 






EDIT 
BUFFER 


**~ FIXED 


FIRST -+ 


SYMBOL 
TABLE 


VARIABLE 


USRORG — *■ 


USER RAM 
AREA 




LAST -*■ 






(USRORG DEFAULT) — * 







If the USRORG has been redefined by entering a new value after an "O" 
command, the area from USRORG to LAST becomes a protected 
memory area for automatic assemblies, similar to protecting RAM by 
the BASIC "MEMORY SIZE" option. If assemblies into memory are per- 
formed with automatic origin (no /MO switch), the assembler will only 
use the available RAM up to USRORG. The user RAM area may be used 
to hold other programs or data as desired, 

The edit buffer is also limited by USRORG; it connot go beyond 
this location. 
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Assembling With an Absolute Origin 

There is another switch associated with in memory assemblies the 
Absolute Origin switch, /AO. 

All assemblies that are performed that are not to memory (no /IM 
switch) must have an absolute origin by means of an ORG statement 

o^^ haVe Seea For exam P Ie > to assemble a program that will load at 
8000H, we specify 

ORG 8000H ;PROGRAM ORIGIN 

and assemble by means of *A/LP, or other "A" command with swit- 
ches. 

The default condition for non-memory assemblies is an assembly with 
absolute origin and is equivalent to 

*A/AO 

All assemblies in which the object code is written to cassette tape are 
absolute assemblies. 

EDTASM-PLUS is primarily designed for in-memory assemblies with 
//M^ n i 9in i. determined automati ca!ly by EDTASM-PLUS or the user 
(/MO). In these cases no user ORG pseudo-ops are required. It is possi- 
ble to perform in-memory absolute assemblies with user-specified 
ORGs, but this technique is not recommended. 

Absolute assemblies may be performed in memory by the sequence 

*A/IM/AO or *A/IM/AO/MO 
When an absolute origin assembly is done, ORG pseudo-ops after the 
first are not relative to the starting address of the program as they are 
when /AO is not used. In an absolute origin assembly, the source line 
ORG $ + 100 ;LEAVE TABLE AREA 

will adjust the Assembler location counter by 100 as we described 
earlier in this chapter. 
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Assembler Expression Evaluation 

EDTASM-PLCJS includes many new operators and expression 

evaluation features. Expressions may be used in the assembly to 
simplify the programmer's task by automatically generating such 
things as table lengths, string lengths, constants, addresses, and other 
data. Let us see how these operators ...uh... operate. 

Addition and subtraction are represented by " + " and " - ", respec- 
tively. Some examples of their use are shown in the code below: 

TABLE DEFB 23 + 80H ; FLAG AND CONSTANT 

DEFB 25 + 80H 

DEFB 17 + 80H 

DEFB 35 + 80H 

TABSZ DEFB $-TABLE ;FlND SIZE OF TABLE 

In this example a table of constants is generated, with bit 7, the most 
significant bit, being set for each entry. Adding the 80H to set the bit 
is less abstract than calculating the value by hand for the DEFB 
operand. 

The size of the table is nicely defined by the expression "$ -TABLE", 
which generates a symbol TABSZ that is equal to the number of en- 
tries in TABLE. Additional entries may be added to the table (by 
reassembling) without having to refigure the size. TABSZ can be used 
as immediate data: 



LD 



B,TABSZ 



;LOAD SIZE OF TABLE 



Multiplication and division are represented by "*" and 7", respec- 
tively. Their use is less frequent than addition and subtraction, but in 
certain cases they may be very handy. 

One example of the use of multiply might be the generation of a table 
size based on two variables, NEFST, the number of entries in the table, 
and ENTSZ, the number of bytes per entry. These parameters could 
easily be changed by reassembling without affecting calculations 
related to the size of the table. 



LD 



BC,NENT* ENTSZ ;COMPUTE TABLE SIZE 



The example below uses the division operator to find the starting 
point for a binary search based on table size. 
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LD 



HUNENT* ENTSZ/2 + TABLE 



When a divide is performed, the division is done in integer fashion. If 
the result is not an integer, as in 13/2, the quotient is used as the 
result and the remainder is ignored. In general, expressions used in 
assemblies must be able to be equated to a 16-bit integer. 

Logical operators allow the user to perform logical ANDs, ORs, and 
exclusive ORs on address and constant data in assemblies. These 
operators are used infrequently, but may be quite useful for 
generating certain types of data. The logical OR function is 
represented by ".OR." or "!", the logical AND by ".AND." or "&", and 
the logical exclusive OR by ".XOR." These operators must be used 
between two terms in an expression. 



0000 0A 


00100 


DEFB 


0A.OR.2 


LOGICAL OR 


0001 0B 


00101 


DEFB 


0A!3 


LOGICAL OR 


0002 07 


00110 


DEFB 


1FH.AND.7 


LOGICAL AND 


0003 07 


00111 


DEFB 


1FH&7 


LOGICAL AND 


0004 18 


00120 


DEFB 


1FH.XORJ 


LOGICAL EXCLUSIVE OR 


0000 


00130 


END 







00000 TOTAL ERRORS 

The .NOT. operator takes the one's complement of a value or ex- 
pression. The .NOT. is used before one term. 

0000 AA 00100 DEFB .NOT.55H ;ONE'S COMPLEMENT 
000155 00110 DEFB .NOT.AAH ;ONE'S COMPLEMENT 

The shift operator is represented by a less than symbol ( < ). The 
shift operator may be used to generate data shifted left any number 
of bit positions by a positive shift count or right any number of bit 
positions by a negative shift count. 

7173 38 00100 DEFB 7< 3 ;SET BITS 5,4,3 

7174 001 E 00110 DEFW 3C00H <-1 ;GENERATE WORD 

ADDRESS 
0000 00120 END 

00000 TOTAL ERRORS 

NOTE: Some lines which fit as one line on your 
computer screen will not fit on this manual page as 
one line. These lines have been continued on a se- 
cond line with the information continued beneath 
the last column. 
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The modulo operator is represented by a ".MOD." The modulo 
operator is used to find the remainder result of a division of two 
numbers. The remainder result is then used as the data value. 



0000 02 00100 DEFB 

0001 03 00110 DEFB 
0000 00120 END 
00000 TOTAL ERRORS 



56.MOD.6 ;56/6 IS 9 REMAINDER 2 
111.MOD.9 ;111/9 IS 12 REMAINDER 3 



The equals (.EQU.) and not equals (.NEQ.) operators are used 
between two terms in an expression. If the result of the expression is 
true, a 0FFH value is generated; if the result is false, a value is pro- 
duced. These operators find limited use, but may be used in the con- 
ditional assembly feature discussed next in this chapter. 



0000 FF 00100 


DEFB 


1.NEQ.0 


0001 00 00120 


DEFB 


1.NEQ.1 


0000 00130 


END 




00000 TOTAL ERRORS 







Parentheses "( )" may be used to group parts of an expression if the 
first operator in an expression is not a left parenthesis. For ex- 
ample, 

LD HL,3*(5 + 2) 
is valid, but 

LD HU(5 + 2)*3 

is invalid and will cause an error. 

Constants may be used in an expression, of course. Constants with 
an O or Q suffix are octal constants, constants with an H suffix are 
hexadecimal, and unsuffixed constants or those with a T suffix are 
decimal. An ASCII character is always bracketed by single quotes. 

77H = 1670 = 167Q = 119T = 119 
'A' = ASCII A 

The Assembler location counter is represented by a dollar sign ($) 
or period (.). 

The operators that may be used in assembly, and their order of 
precedence are shown on the next page. The order of precedence is 
used to determine which parts of the expression will be evaluated first. 
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Operator 




Operation 


Precedence 










Level 


Lowest 










Precedence 


.EQU. (or 


= ) 


equals 


1 






.NEQ. 




not equals 


1 






+ 




addition 


2 






- 




subtraction 


2 






.OR. (or !) 




logical OR 


3 






.XOR. 




logical exclusive OR 


3 






.AND. (or 


&) 


logical AND 


4 






# 




multiplication 


5 






/ 




division 


5 






< 




shift 


5 


V 


.MOD. 




modulo 


5 


Highest 


.NOT. 




NOT (Is complement) 


6 


Precedence 


( ) 




parentheses 


7 



Operations of the same precedence are applied left to right. 



Conditional Assembly 



EDTASM-PLCS includes two pseudo-ops that we have not discussed 
up to this point. The COND(itional) and ENDC(onditional) pseudo-ops 
permit conditional assembly. The formats of the COND and ENDC 
pseudo-ops are 

COND (expression) (label not allowed) 
ENDC (label not allowed) 

If the value of the expression is non-zero (true), then the source code 
between the COND and the matching ENDC is assembled; if the value 
of the expression is zero (false), then the source code between the 
COND and ENDC is not assembled. 

Let us see how this is utilized. 

ASSEMBLE IF 48K RAM 
INITIALIZE STACK POINTER 
INITIALIZE BUFFER POINTER 
;END CONDITIONAL 



COND 


M4SK 


LD 


SP,0C0O0H 


LD 


HL0AF80H 


ENDC 
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In the example on the preceding page, the two load instructions are 
assembled if and only if symbol M48K is equal to a non-zero value. 
Typically this would be done by: 

M48K EQU 1 ;SET48K 

Any number of conditional assembly sets may be used; they may even 



ASSEMBLE IF 48K RAM 
INITIALIZE STACK POINTER 
INITIALIZE BUFFER POINTER 
ASSEMBLE IF CASSETTE 
;SET CASSETTE FLAG 
[STORE 



Every COND must have a corresponding ENDC, and they may be 
nested up to 255 levels (although that is somewhat outrageous!). 

Suppose that we have two sets of conflicting code. One set is to be 
assembled if memory is 64K while the other is not assembled for 64K, 
and vice versa. We can use the ".NEQ." operator to assemble either one 
set or the other: 



be nested as in 




COND 


M48K 


LD 


SP,0C000H 


LD 


HU0AF80H 


COND 


CASS 


LD 


A,1 


LD 


(CASSF),A 


ENDC 




ENDC 





M64K.NEQ.0 
SP,0 



COND 

LD 

ENDC 

COND M64K.EQU.0 
LD SP,7F00H 

ENDC 



ASSEMBLE FOR 64K SYSTEMS 
INITIALIZE STACK POINTER 

ASSEMBLE FOR NON-64K SYSTEMS 
;INITIALIZE STACK POINTER 



If M64K is non-zero, the stack pointer is loaded with 0, while if M64K is 
zero, the stack pointer is loaded with 7F00H. 

We now come to a philosophical question.. .Why do we want to condi- 
tionally assemble code? For some very good reasons. Suppose that you 
are in the software business producing TRS-80 software for various con- 
figurations of systems. Some systems have one cassette and one disk 
and 48K of RAM, other systems have four disks, no cassettes, and 32K 
of RAM, and so forth. It is very convenient to write one master version of 
a program that will handle all possible configurations of systems by 
conditionally assembling only that code which is applicable to the in- 
dividual system. 
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The alternative to a master version is a separate version for each con- 
figuration. If this approach is used, every version must be changed if 
new code is put in, or existing code modified. It is much more conve- 
nient and accurate to change only one master version and use condi- 
tional assembly. 

When the conditional assembly approach is used, the symbols for each 
COND are usually conveniently grouped at the beginning of the listing, 
so that they may be modified to reflect the desired configuration before 
assembly: 

;CHANGE THESE PARAMETERS FOR SYSTEM GENERATION 



NODISK EQU 1 

NOCAS EQU 1 

MEMSZ EQU 48 

LP EQU 1 

SERIAL EQU 

;END OF SYSTEM EQUATES 



NUMBER OF DISKS 
NUMBER OF CASSETTES 
MEMORY SIZE 
LINE PRINTER = 1, NONE = 
RS-232 = 1,NONE = 
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Chapter Four 
Assembler Macro Capability 

What Is a Macro? 
Using Parameters in Macros 
When Can Macros Be Used? 
Rules for Macro Definitions 
Rules for Macro Reference 
Suppressing the Listing of a Macro 
Macro Labels Using #$YM 
Further Samples of Macro Usage 
Symbol Table Codes 
Assembler Error Messages 
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What Is a Macro? 

A macro is a way of automatically generating assembly- 
language instructions. One way to think of macros is as "in-line" 

subroutines. Suppose, for example, that in an assembly-language 
program that we are writing we use the HL register pair to hold 16-bit 
values that need to be shifted left n number of bit positions. If we hold 
a shift count in the B register, then an easy set of instructions to do 
this would be 

00400 LOOP ADD HL,HL ;SHIFT HL LEFT, LOGICAL 

00410 DJNZ LOOP ;CONTINUE FOR N TIMES 

This code performs a left shift on the HL register by adding it to itself 
n times, where n is a count of 1-15 in the B register. (The DJNZ in- 
struction decrements the count in the B register and jumps to LOOP if 
the result of the decrement is not zero.) 

Now, one way to generalize this function is to make it a 
subroutine by adding a RET(urn) instruction and moving it to an area 
of the assembly-language program where it can be CALLed every 
time we want to perform a shift of HL. Before each call, the B register 
is loaded with a count of 1 through 15 that represents the number of 
times HL is to be shifted. Two CALLs and the subroutine itself are 
shown in the code below: 



00100 
00110 

00550 
00560 



LD 



B,3 



;LOAD B FOR SHIFT OF HL 3 
BITS 
CALL SHFTHL ;SHIFT HL 



LD B,10 ;LOAD B FOR SHIFT OF HL 10 

BITS 
CALL SHFTHL ;SHIFT HL 



10000 SHFTHL ADD HL,HL 
10010 DJNZ SHFTHL 

10020 RET 

64 



;SHIFT HL LEFT, LOGICAL 
;CONTINUE FOR N TIMES 
RETURN TO CALLING CODE 



NOTE. Some lines which fit as one line on your 
computer screen will not fit on this manual page as 
one line. These lines have been continued on a se- 
cond line with the information continued beneath 
the last column. 

In the code above, we have used three dots to represent intervening 
code between the two CALLs and the actual subroutine. 

A second way of generalizing the shift HL function is to make it a 
macro. First, we define the two steps for the shift as a macro defini- 
tion and give this definition a name: 



00018 SHFTHL MACRO 
00020 ADD HL,HL 

00022 DJNZ $-1 

00024 ENDM 



DEFINE MACRO 
SHIFT HL, LOGICAL 
CONTINUE FOR N TIMES 
END DEFINITION 



The first pseudo-op, MACRO, essentially told the assembler that the 
following code was a macro named "SHFTHL". The second pseudo- 
op, ENDM, defined the end of the macro. 

Note that this code does not generate any instructions at this 
point — it is simply a definition that the assembler notes. 

We can reference the macro by referring to the macro name. Each 
time we use the macro name in the opcode field of an assembly- 
language line, the assembler decodes the name as a macro reference, 
finds the corresponding macro definition, and generates the instruc- 
tions that have been defined for that macro. The complete source 
code for two references to the macro and the macro definition is; 



00018 SHFTHL MACRO 



00020 


ADD HL,HL 


00022 


DJNZ $-1 


00024 


ENDM 


00100 


LD B,3 


00102 


SHFTHL 


00550 


LD B,10 


00560 


SHFTHL 


01000 


END 



DEFINE MACRO 

SHIFT HL, LOGICAL 

CONTINUE FOR N TIMES 

END DEFINITION 

LOAD B FOR SHIFT OF HL 3 BITS 

SHIFT HL MACRO 

LOAD B FOR SHIFT OF HL 10 BITS 

SHIFT HL MACRO 
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The assembled version of this source code 
references are expanded into sets of the two 
the macro definition. The macro definition 
without generating any code at that point. 



shows that the macro 
instructions defined in 
itself is simply listed 





00018 SHFTHL MACRO 




;DEFINE MACRO 




00020 


ADD 


HL,HL 


;SHIFT HL, LOGICAL 




00022 


DJN2 


$-1 


;CONTINUE FOR N 
TIMES 




00024 


ENDM 




;END DEFINITION 


00000603 


00100 


LD 


B,3 


;LOAD B FOR SHIFT 
OF HL 3 BITS 




00102 


SHFTHL 




;SHIFT HL MACRO 


0002 29 




ADD 


HL,HL 


;SHIFT HL, LOGICAL 


0003 10FD 




DJNZ 
ENDM 


$-1 


;CONTINUE FOR N 

TIMES 
;END DEFINITION 


0005 060A 


00550 


LD 


B,10 


;LOAD B FOR SHIFT 
OF HL 10 BITS 




00560 


SHFTHL 




;SHIFT HL MACRO 


000729 




ADD 


HL,HL 


;SH!FT HL, LOGICAL 


0008 10FD 




DJNZ 
ENDM 


$-1 


;CONTlNUE FOR N 

TIMES 
;END DEFINITION 


0000 


01000 


END 






00000 TOTAL ERRORS 









NOTE. Some lines which fit as one line on your 
computer screen will not fit on this manual page as 
one line. These lines have been continued on a se- 
cond line with the information continued beneath 
the last column. 

Note that in the macro definition, we avoided using labels other 
than the macro name itself. The reason for this is that as the 
Assembler simply reproduces the macro definition every time it en- 
counters a macro reference, it would reproduce the labels as well. 
More than one macro reference would produce doubly defined 
labels, which would result in an Assembler error diagnostic message. 
For a technique to use labels inside macros, see the section in this 
chapter labeled "Macro Labels Using #$YM". 
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Using Parameters In Macros 

Using the macro on the preceeding page, we can easily and 
automatically generate the code for the shift function anytime we 
reference the macro by using the name in the op code field of an 
assembly-language source line. 

This technique can be used for any number of lines of code that are 
defined by a macro definition and for any number of individual 
macros. Each macro definition, of course, must have a unique name 
to be referenced. 

Generating a set of predefined instructions is only a portion of the 
power of macro usage, however. We can generate not only a set of 
specific instructions, but sets of instructions that use different 
parameters expressed in the macro reference. Let us see how this 
works. 

In the SHFTHL macro above, we had to load the B register with a 
count prior to referencing the macro. By using the count as a 
parameter, we can automatically generate the proper load B instruc- 
tion. The macro definition for this is: 



00018 SHFTHL 


MACRO 


#COUNT 


;DEFINE MACRO 


00020 


LD 


B,#COUNT 


;LOAD COUNT 


00022 


ADD 


HL,HL 


;SHIFT HL, LOGICAL 


00024 


DJNZ 


$-1 


;CONTINUE FOR N TIMES 


00026 


ENDM 







The macro definition line here has one parameter expressed as an ar- 
bitrary name. This name is used in the macro definition code as a 
general parameter. When the macro is referenced by invoking it with 
the name SHFTHL, the reference also includes a parameter which will 
take the place of #COCJNT in the macro expansion. A sample 
reference is: 



00550 



SHFTHL 10 



and the expansion for this reference is: 
00550 



SHFTHL 


10 


LD 


B,10 


ADD 


HL,HL 


DJNZ 


$-1 


ENDM 





SHIFT HL 10 BITS 



SHIFT HL 10 BITS 
LOAD COUNT 
SHIFT HL, LOGICAL 
CONTINUE FOR N TIMES 
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We have left out the source code generated by the macro expansion, 
but the reader can see that the LD B instruction has used the 
parameter of 10 from the macro reference line as the parameter to be 
used in the load. The Assembler has automatically generated a 
set of instructions with the specified parameter. 

The number of parameters used in a macro may be any number that 
may fit into a source line. Let us try another example that illustrates 
how several parameters may be used. In this example, we will use the 
block move instruction of the Z-80, the LD1R. The LD1R moves a block 
of data from a source location to a destination location. Prior to the 
LDIR, the HL register is loaded with the source address, the DE 
register is loaded with the destination address, and the BC register is 
loaded with the number of bytes to move. A typical sequence is: 

SOURCE ADDRESS 

DESTINATION ADDRESS 

100 BYTES IN BLOCK 

MOVE SRCE BLK TO DEST BLK 

The above code moves the bytes in locations 17000 through 17099 to 
locations 18000 through 18099. 

Now, let us take the above code and make a general macro out of it, 
using the source address, destination address, and number of bytes to 
move as parameters. When we finish we will have a general macro 
that can be used anytime we want to move a block of data. 

00050 MOVE MACRO #SRCE,#DEST,#NUM 



01000 


LD 


HL,17000 


01010 


LD 


DE,18000 


01020 


LD 


BC,64H 


01030 


LDIR 





00052 
00054 
00056 
00058 
00060 



LD 

LD 

LD 

LDIR 

ENDM 



HL 5 #SRCE 
DEADEST 
BCJNUM 



;LOAD SOURCE ADDRESS 
;LOAD DESTINATION ADDRESS 
;LOAD BYTE COUNT 
;MOVE BLOCK 



The above macro definition uses three parameters, #SRCE, #DEST, 
and #NUM, which are referenced inside the macro. To reference the 
MOVE macro, the reference line would include three parameters to be 
used in the macro expansion. These parameters could be any values, 
symbols, or expressions that would normally be used in coding the 
four instructions. Typical references for the MOVE macro would be 

02000 MOVE 1 7000,1 8000,64H 

which duplicates the "typical" sequence for LDIR we saw previously, 
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03000 MOVE BUFF1,SCREEN,1024 

which uses symbolic addresses for the source and destination, and 

04000 MOVE BUFF2 + 1024,3C00H,1024 

which uses an expression for one of the parameters. 
The macro expansion for the first example would be 

02000 MOVE 17000,18000,64m 



LD 


HL,17000 


;LOAD SOURCE ADDRESS 


LD 


DE,18000 


;LOAD DESTINATION ADDRESS 


LD 


BC,64H 


;LOAD BYTE COUNT 


LDIR 




;MOVE BLOCK 


ENDM 







Parameter usage in the macro may involve simple loads as we have 
seen above, or may be much more complicated. There is no reason 
that we could not subtract two parameters, such as #ARG2~#ARG 1 , or 
perform other manipulations with the parameters, just as we do in 
writing in-line code. 
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When Can Macros Be Osecl? 

What are the relative merits of macros versus subroutines? In the 
subroutine case the code is generated only one time and exists in 
one area of memory. Aside from the overhead of the CALL and 
RET(urn) instructions, subroutine usage is very efficient in terms 
of speed and extremely efficient in use of memory. When one 
must perform a set of predefined instructions over and over, 
subroutines may be used to advantage. 

However, when parameters are Involved, referencing the 
macro and having the Assembler automatically generate the pro- 
per code is extremely efficient in terms of program development 
time. Nobody likes to sit down and write long sequences of in- 
structions, and EDTASM-PLUS makes the task much easier by 
the use of macros. 

The one disadvantage of macros, of course, is the amount of 
memory that is used when many macros are expanded. In the ear- 
ly days of computers (five years ago), this was a critical factor. 
However, memory is very inexpensive today, and programming 
time is much more important. For all intents and purposes, the 
amount of memory used by macros can be ignored. 

As a matter of fact, using macros in EDTASM-PLCJS will probably 
result in less memory being used! This is because the edit buffer 
also uses memory space. One-time definitions of macros with 
macro references are much more efficient in terms of number of 
characters of source code than repeating the source code without 
using macros! 

Macro usage has many exciting possibilities on the TRS-80. 
Because each macro definition may have many arguments, and 
there may be any reasonable number of macro definitions, whole 
applications languages may be defined and utilized. For exam- 
ple, it is not hard to visualize a high-speed word processing 
language written almost entirely in macros. We will whet your ap- 
petite by showing a sample of how this could be performed: 
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01010 


SCAN 


Pl,BACK 


01020 


JP 


M,NFND 


01030 


SCAN 


PI,FWRD 


01040 


JP 


M.NFND 


01050 


DELS 


CS.CE 


01060 


DELB 


BS,BE 



01000 ;THIS SEQUENCE DELETES A PARAGRAPH 

;SCAN FOR PARAGRAPH MARK 

GO IF NOT FOUND 

;SCAN FOR PARAGRAPH MARK 

;GO IF NOT FOUND 

DELETE SCREEN CHARACTERS 

DELETE BUFFER CHARACTERS 

Another example of macro use is the simulation of another 
assembly-language on the TRS-80. Using macros, it is relatively easy 
to construct a cross-assembler to, say, assemble source code for the 
6800 microprocessor on the TRS-80, or to assemble source code and 
to execute code for a purely hypothetical machine! 

An example of macros for the 6800 is shown below: 



02000 QE200 LDX BUFFER 

02010 LDAA 256 

02020 ADDB 23 

02030 BNE QE302 

02040 JMP QE125 



LOAD INDEX WITH ADDRESS 

NUMBER OF BYTES 

ADJUST B REGISTER 

GO IF NOT EQUAL 

;GO FOR NEXT SET OF VALUES 



The corresponding macro definition for the JMP macro would assem- 
ble the proper machine language code for the 6800 by: 



00100 JMP 


MACRO 


#ARG1 ;JMP DEFINITION 


00101 


DEFB 


7EH ;OP CODE FOR JMP 


00102 


DEFB 


#ARG1/256 ;EXTENDED ADDRESS 


00103 


DEFB 


#ARG1.MOD.256 


00104 


ENDM 





Before showing some further examples of macro usage, let us first set 
down the rules for macro definitions and references. 
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Rules for Macro Definitions 

As we have seen in the previous example, all macros in EDT ASM- 
PLUS consist of a macro definition line, a body of code, and an 
end macro line: 

NAME MACRO #P1,#P2,#P3,...#PN 
(body of macro) 
ENDM 

The label, or macro name, is required and can be any valid 
assembly-language label. The parameters are optional depending 
upon the code in the body of the macro. Here are the rules for the 
parameters: 

The first character of the dummy parameter must be a "#". 

The maximum length of the dummy parameter string is 16 
characters, including the "#". 

Commas must be used between parameters. 

The last parameter string must be terminated by a carriage 
return, space, tab, or semicolon. 

Parameter strings may contain any characters except delimiters 
(",", space, tab, ";") or the "#" symbol. 

The ENDM is always the last statement in the macro. It cannot 
have a label, or the Assembler will not recognize it as an end macro 
pseudo-op. 

The body of the macro can consist of any valid assembly-language 
lines with Z-80 operation codes, pseudo-ops, operands, and com- 
ments. Normally, labels are not permitted in the body as they will 
cause doubly-defined labels if the macro is referenced more than 
once. (We will explain a special technique for label use later in this 
chapter.) Dummy arguments referenced within the body of the macro 
use the same strings as defined in the MACRO line. 

Nested macros are not permitted. This is an important point. We 
cannot have a macro definition such as: 
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00030 SHIFT 


MACRO 


#ARG1 


;SHIFT MACRO 


00031 


LD 


B,#ARG1 


;LOAD SHIFT COUNT 


00032 


ADD 


HL,HL 


;SHIFT ONE BIT POS'N 


00033 TEST 


MACRO 




;TEST BIT 2 


00034 


BIT 


2,C 


;SET FLAG 


00035 


ENDM 






00036 


DJNZ 


$-3 


;LOOP IF NOT DONE 


00037 


ENDM 







It is also illegal for a macro definition to contain a macro reference. 

As we have seen, the macro definition does not generate any code at 
the time of definition. Code is only generated when the macro is 
referenced. The macro definition is normally listed with line numbers, 
but without generated code. This listing can be suppressed by the 
♦ LIST ON and * LIST OFF Assembler commands, just as any source 
lines may be controlled. 

Two new Assembler commands, *MLIST ON and *ML1ST 
OFF, allow the listing of macro expansions to be suppressed. We will 
discuss these in a later section. 
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Rules for Macro Reference 

We have already seen a few examples of macro definition and expan- 
sion. One point that was implied, but may not be obvious, is that the 
macro definition must come before any reference to it. It is con- 
sidered good assembly-language programming practice to group all 
of the macro definitions close to the beginning of the assembly- 
language program so that the Assembler will have processed the 
definitions before any reference to them. A "MACRO FWD 
REFERENCE" error occurs if this is not done. 

The label on a macro reference line is optional and causes no pro- 
blem if used, as it is not a part of the actual macro expansion. 

Parameters are optional and depend upon the parameters used in 
the macro definition. The parameters are substituted in the same 
order as they are defined in the macro definition. The first parameter 
corresponds to the first dummy, the second to the second dummy, 
and so forth. 

The rules for the parameters in the macro reference line are: 

Each parameter string must be less than 16 characters. 

Each parameter must be separated by commas. 

The last parameter must be terminated by a space, car- 
riage return, tab, or semi-colon. 

Delimiters (space, semi-colon, tab, comma) may be used 
in a parameter string if they are enclosed by single 
quotes. 

The last point may be somewhat confusing. If a text parameter is used 
in the body of the macro, then a delimiter, such as a blank imbedded 
in the text, may confuse the assembler. 

An example of this is shown in the macro and reference on the op- 
posite page which uses a DEFM, DEFine Message, within the body of 
the macro to assemble a text parameter. We would like to have the 
message "AN EVEN BREAK" assemble into the macro reference. The 
imbedded blank, however, fools the Assembler into terminating the 
parameter after "AN" and only the "A" and "N" are generated. 
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00100 TEXT 


MACRO 


#ARG1 






00110 


DEFM 


'#ARG1' 






00120 


ENDM 








00130 


TEXT 


AN EVEN BREAK 


0000 


41 




DEFM 


'AN' 


0001 


4E 




ENDM 




0000 




00140 


END 




00000 TOTAL ERRORS 







TEXT 



652C 



This error can be remedied by enclosing the entire parameter in 
quotes in the macro reference. The assembler then treats the text as a 
single parameter and the message is assembled properly. 

When a single quote must be generated itself, a special case arises. 
The single quote is denoted by two successive single quotes. The text 
string "ABCDEF" must be coded in the macro reference line above as 
'ABC'DEF' with quotes around the entire text and a pair of single 
quotes to represent the desired single quote. 
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Suppressing the Listing of a Macro 

It is often desirable to suppress the listing of macro expansions. 
This is not done so much to keep proprietary code from prying eyes 
(although this is a use), but to reduce the listing to a more 
manageable and readable form. The * MUST OFF command sets the 
no print mode for macro expansions and the &ML1ST ON restores 
printing. The MLIST commands are completely separate from the 
LIST commands. The *L1ST commands control all assembly line 
printing while the * MLIST commands control only printing for macro 
expansions. In the example below note that the "LD D,4" instruction is 
not in a macro expansion and is printed even though the macro ex- 
pansion is not. 







00100 PRINT 


MACRO 


#ARG1,#ARG2,#ARG3 






00110 




LD 


A,#ARG1 






00120 




LD 


B,#ARG2 






00130 




LD 


C,#ARG3 






00140 




ENDM 








00150 


* MLIST OFF 




0000 


1604 


00160 




LD 


D,4 


0002 




00170 




PRINT 


1,2,3 






00180 


♦ MLIST ON 




0008 




00190 




PRINT 


4,5,6 


0008 


3E04 






LD 


A,4 


000A 


0605 






LD 


B,5 


oooc 


0E06 






LD 
ENDM 


C,6 


0000 




00200 




END 





00000 TOTAL ERRORS 



Macro Labels Osing #$YM 

Every time a macro is expanded, an implicit parameter named #$YM 
is generated. In effect, this parameter is set equal to the number of 
times all macros have been expanded. If five macros have been used 
since the start of assembly, #$YM = 5; if 15 macros have been ex- 
panded since the start of assembly, #$YM= 15. 
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As the value of #$YM is unique for each macro expansion, it may be 
used to create a label for a macro without causing doubly defined 
labels. Let us see how this works. 

Every time #$YM is used in a macro, a four-character string represen- 
ting the current value (macro count) of #$YM is substituted in place of 
the string #$YM. Labels can therefore be created in the macro by 
defining such strings as A#$YM or B#$YM. When the macro is ex- 
panded, these labels will become A000, A0003, B0015, or other 
unique labels for the macro. 

The example below shows the use of #$YM in creating labels for two 
macros, each of which is expanded twice. 

7000 00100 ORG 7000H 

MACRO 
JP A#$YM 

ENDM 
MACRO 
JP B#$YM 

ENDM 
FIRST 
JP 

ENDM 
SECND 
JP 

ENDM 
FIRST 
JP 

ENDM 
SECND 
JP 

ENDM 
END 



00100 

00110 FIRST 
00115 A#$YM 
00120 

00130 SECND 
00135 B#$YM 
00140 
00150 



7000 C30070 



7003 C30370 



7006 C30670 



7009 C30970 



AOOOO 



00160 



B0001 



00170 



A0002 



00180 



B0003 



AOOOO 



B0001 



A0002 



B0003 



;#$YM = 0000 



;#$YM=0001 



;#$YM = 0002 



;#$YM = 0003 



0000 



00190 



00000 TOTAL ERRORS 
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Further Samples of Macro Osage 

In this section we will illustrate further use of macros by two examples, 
a macro for subroutine calls, and a macro to fill a portion of the 
screen with a given character. 

Osing macros for subroutine calls combines the advantages of 
both macros and subroutines. Subroutines take up minimal memory, 
but may require a great deal of overhead in loading parameters before 
a CALL is actually made to the subroutine. 

In this example, we define a macro that sets up the necessary 
parameters for a CALL to a subroutine that performs disk reads and 
writes. The parameters that must be initialized before the subroutine is 
called are: 

Disk drive number in A register 
Sector number of read or write in B register 
Track number of read or write in C register 
Function in D register: = read, 1 = write 
Buffer address in HL register- 
Normally these must be defined by performing five loads before the 
CALL to DISKIO, but this macro permits us to write the parameters in 
a single^ line: 



00100 I 


DISKIO MACRO 


#ARG1,#ARG2,#ARG3, 






#ARG4,#ARG5 


00110 


LD 


A,#ARG1 


00120 


LD 


B,#ARG2 


00130 


LD 


C,#ARG3 


00140 


LD 


D,#ARG4 


00150 


LD 


HL,#ARG5 


00160 


CALL 


DISKDR 


00170 


ENDM 




00180 ; 


EXAMPLE OF EQUATE FOR FUNCTIONS 



0000 
0001 



00190 READ EQU 

00200 WRITE EQU 1 

00210 ; EXAMPLE OF MACRO USE FOR READING 
TRACK 10, SECTOR 5 INTO 
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00220 


BUFFER AT 8000H FROM DISK DRIVE 1 






00230 




(Single line call) 


^ 






00240 


DISKIO 


1,5,10, READ,8000H 


7235 


3E01 




LD 


A,1 


3 


7237 


0605 




LD 


B,5 


n 


7239 


0E0A 




LD 


C,10 


o 


723B 


1600 




LD 


D,READ 


CD 


723D 


210080 




LD 


HL,8000H 


J2. 


7240 


CD4372 




CALL 
ENDM 


DISKDR J 


3 






00250 


DUMMY ADDRESS FOR DISKDR 










SUBROUTINE 






7243 




00260 


DISKDR EQU 


$ 




0000 




00270 


END 






00000 TOTAL ERRORS 









NOTE. Some lines which lit as one line on your 
computer screen will not fit on this manual page as 
one line. These Sines have been continued on a 
second line with the information continued beneath 
the last column. 

The macro for filling a screen segment uses four arguments for the 
screen starting and ending position and one argument for the fill 
character. When the macro is expanded, the HL register pair is loaded 
with the screen address of the starting line and character position 
(#ARG1*64 + #ARG2 + 3C00H), the BC register pair with the screen 
address of the ending line and character position (ARG#3#64 
+ ARG4 + 3C00H), and the A register with the character to be filled. 
This character is filled to the screen as long as HL and BC are not 
equal; HL is incremented by one each time through the loop. 

Two #$YM type labels are used within the macro to prevent duplicate 
references for expansion of more than one macro. 

00100 FILLSC MACRO #ARG1 ,#ARG2,#ARG3 J 

#ARG4,#ARG5 

00110 LD HL,#ARG1*64 + #ARG2 

+ 3C00H 

001 20 LD BC,#ARG3 * 64 + #ARG4 

+ 3C00H 
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00130 




LD 


A,'#ARG5' 






00140 D#$YM 


LD 


(HL),A 






00150 




PUSH 


HL 






00160 




OR 


A 






00170 




SBC 


HL,BC 






00180 




POP 


HL 






00190 




JR 


Z,F#$YM 






00200 




INC 


HL 






00210 




JR 


D#$YM 






00220 F#$YM 


EQU 


$ 






00230 




ENDM 








00240 


SAMPLE CALL TO FILL LINE 1, 
CHARACTER POSITION 7 






00250; 


THROUGH LINE 9 


, CHARACTER POSITION 








23 WITH A CHARS. 






00260; 


(single line invokes macro) — y 






00270 




FILLSC 


7,7,9,23,A^ 


721 E 


21C73D 






LD 


HL,7*64 + 7 + 3C00H ' 


7221 


01573E 






LD 


BC,9*64 + 23 + 3C00H 


7224 


3E41 






LD 


A/A' 


7226 


11 




D0000 


LD 


(HL),A 


7227 


E5 






PUSH 


HL 


7228 


B7 






OR 


A ► 


7229 


ED42 






SBC 


HL,BC 


722B 


E1 






POP 


HL 


722C 


2803 






JR 


Z,F0000 


722E 


23 






INC 


HL 


722F 


18F5 






JR 


D0000 


7231 






F0000 


EQU 

ENDM 


$ J 


0000 




00280 




END 




00000 TOTAL ERRORS 









NOTE, Some lines which fit as one line on your 
computer screen will not fit on this manual page as 
one line. These lines have been continued on a 
second line with the information continued beneath 

the last column. 



Symbol Table Codes 



Every time an assembly is run, the symbol table is compiled by the 
Assembler and listed (if the /NS switch is inactive). The Assembler 
uses special codes to help the user recognize what various labels in 
the symbol table represent. 

An undefined code ("CI") is listed if the symbol is erroneously 
referenced but never defined. 



UNDEFINED SYMBOL 
0000 3E00 00100 

0000 00110 

00001 TOTAL ERRORS 



LD 
END 



A, VALUE ;LOAD VALUE 



VALUE 0000 U 
A macro code ("M") is listed if the symbol is a macro name. 
00100 EXMPLE MACRO 





00110 


LD A, 20 




00120 


ENDM 




00130 


EXMPLE 


0000 3E14 




LD A, 20 
ENDM 


0000 


00140 


END 



00000 TOTAL ERRORS 



EXMPLE 



M 



A forward reference code ("F") is listed if the symbol is a macro 
name referenced before definition of the macro. 



A, 20 



BAD OPCODE 




00090 EXMPLE 




MACRO FWD REF 




00100 EXMPLE MACRO 




00110 


LD 


00120 


ENDM 


0000 00140 


END 


00002 TOTAL ERRORS 





EXMPLE 



UMF 



The redefined symbol code ("R") is listed if the symbol is erroneous- 
ly defined more than one time. 
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MULTIPLE DEFINITION 

0000 3E14 00100 LOOP LD A, 20 

MULTIPLE DEFINITION 

0002 3E14 00110 LOOP LD A,20 

0000 00120 END 

00002 TOTAL ERRORS 

LOOP 0000 R 

The DEFLed symbol code ("D") is listed if the symbol is defined by 
a DEFL pseudo-op. 

000A 00100 EXMPLE DEFL 10 

0014 00110 EXMPLE DEFL 20 

0000 00120 END 

00000 TOTAL ERRORS 

EXMPLE 0014 D 
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Assembler Error Messages 

The following messages are used in the assembly listing to inform the 
user of assembly errors. The error message is used just prior to the 
source line in which the error occurs. The source line is then displayed 
or printed following the error message. 

Message Description and Corrective Action 

BAD ADDRESS Invalid address defined for USRORG command 
or address above LAST or below GSRORG on 
assembly. Use an address between LAST and 
FIRST. 

BAD ADD RES- Operands use incorrect addressing mode. Use 
SING MODE valid addressing for the instruction. 

BAD EXPRES- Syntax of expression in source line incorrect. 
SION Redefine. 

BAD MEMORY Assemble into memory verify does not compare. 
Check RAM. 

BAD LABEL Invalid label has been used. Use 1 to 6 character 

label, starting with an alphabetic character. Do 
not use "reserved" (system) words; check label. 

BAD OPCODE Invalid opcode or pseudo-op mnemonic has 
been used. Check spelling. 

BRANCH OUT Relative address displacement on JR or other in- 
OF RANGE struction is greater than +127 or less than 

-128. Use JP or another instruction. 

DIVISION BY Expression used as a divisor. Use non-zero 
value. 

ENDC WITHOUT ENDC encountered without a prior COND. 
COND Check for existence of COND. 

ENDM WITHOUT ENDM encountered without a prior MACRO. 
MACRO Check for existence of MACRO. 

FIELD OVER- Instruction field cannot hold value used as 

FLOW operand. Change value to fit. 

MACRO FWD Macro invoked before definition. Define macro 
REF before reference. 
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Message Description and Corrective Action 

MISSING Operands missing or incomplete in source line. 

INFORMATION Check format of instruction or pseudo-op. 

MULTIPLY Reference to multiply defined symbol (see next 

DEFINED error). 

SYMBOL 

MULTIPLE Same label was used again. Change to one uni- 

DEFINITION que label for each line. 

NESTED Nested macros are not allowed. Redefine 

MACROS macros. 

NO END STATE- No END pseudo-op at end of source code. Add 

MENT END. 

STACK OVER- Expression too involved for stack. (Should rarely 

FLOW occur.) 

SYMBOL TABLE Too many labels used in source program. 

OVERFLOW Shorten or delete labels (use $). 

SYNTAX ERROR Macro syntax incorrect. Check. 

UNDEFINED Symbol encountered that is not defined as label, 

SYMBOL EQU, DEFL, or MACRO. Define. 
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Basic Z-BUG Operation 

The Z-BUG portion of EDTASM is a newly designed, powerful 
debug package that can be used to debug in-memory assemblies or 
any other machine language code. 

Some of the functions that Z-BGG can perform are: 

A display of the contents of memory locations in byte 
form, word form, ASCII form, and Z-80 mnemonic form. 

Modification of memory locations by many of the above 
formats 

Breakpointing of up to eight locations 

Single-stepping through programs 

Symbolic referencing of symbols in the assembly symbol 
table 

Calculator mode operations 

Because Z-BOG is normally resident together with the Assembler and 
Editor, the entire EDTASM-PLGS package is extremely interactive. 
After errors are found by using Z-BGG, the source program in the Edit 
buffer may be modified, a rapid in-memory assembly performed, and 
another level of debug carried out, all without time-consuming 
cassette activity. 

In the following chapter we will explain the capabilities of Z-BGG in 
detail and use an example of actual program development. 

Z-BGG is entered by entering "Z" while in the system command mode. 
After receiving control, Z-BGG prints the prompt character "#" as 
shown below: 

*Z 
Z-BUG 

# 

To return to the system comma nd mod e at any time, type an "$E" 
after the # prompt ( the "$" is a | SHIFT | [J] ). 

#$E 
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Displaying and Modifying Memory 
Locations in Hexadecimal 

When Z-BGG is initially entered, the "examination mode" is 
mnemonic. Any locations that display in this mode are in the form of 
Z-80 mnemonics. The following sequence shows the effects of this 
mode: 



(enter 
(enter 
(enter 
(enter 



Z-BUG 




#0/ 


Dl 


1/ 


XOR A 


2/ 


JP674 


5/ 


JP4000 



E 




T 




T 




ENTER | ) 



# 



As you can see from the sequence, a location is examined by typing 
in the value of the location, followed by a slash \J\ . Subsequent 
locations are examined by entering a down arrow [Tj . 

In this mode, consecutive instructions are displayed, rather than con- 
secutive bytes. If an instruction is three bytes long, for example, the 
Z-BGG location pointer is incremented to the next instruction for 
display. 

The mnemonic examination mode can be set at any time by entering 
an "$M" after a Z-BGG "#" prompt. The dollar sign character is not 
a dollar sign, but is an ESCAPE character, represented by a 

["SHIFT I \±\ . Many Z-BGG instructions use the ESCAPE in this 
fashion. 



#$M 

L 



(set mnemonic examination mode) 
SHIFT | Q] prints as $ 



There are three other examination modes in Z-BGG. If $B is entered at 
any time, the examination mode is set to byte mode. Byte mode 
displays the data in memory one byte at a time with a value of 
through OFFH displayed as the byte contents. As in the preceding ex- 
ample, we can look at consecutive bytes by using the down arrow 

ffl- 
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#$B 




#0/ 


0F3 


1/ 


OAF 


2/ 


0C3 


3/ 


74 


4/ 


6 



Word mode is set by entering an $W after a # prompt. Word mode 
displays two consecutive bytes as a 16-bit word. This mode is used to 
look at locations containing memory addresses or 16-bit data. The 
display of data is a value from through OFFFFH, with the data ar- 
ranged second byte, first byte in standard Z-80 address orientation. 
Compare these locations with the display from byte mode, for exam- 
ple: 

#$W 

#0/ 0AFF3 

2/ 74C3 

If the specified address in word mode starts on an odd location, odd 
numbered words are displayed: 



1/ 


0C3AF 


3/ 


674 



ASCII mode is set by entering a $A after a # prompt. ASCII mode 
displays the memory locations one byte at a time in ASCII. (The ex- 
amination mode is set to byte and the type-out mode to ASCII.) 



#$A 




#111/ 


R 


112/ 


A 


113/ 


D 


114/ 


I 


115/ 





116/ 




117/ 


S 


118/ 


H 



(Byte 


Mode Equivalent) 


#111/ 


52 


112/ 


41 


113/ 


44 


114/ 


49 


115/ 


4F 


116/ 


20 


117/ 


53 


118/ 


48 



In the example above, a valid ASCII message is displayed, as shown. 
Z-BCJG will attempt to display the 7-bit ASCII equivalent, even if the 
contents of the memory locations do not represent an ASCII message, 
as in: 
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#$A 




#0/ 


S 


1/ 


/ 


2/ 


c 



0/ 


0F3 


1/ 


OAF 


2/ 


0C3 



To display any memory location using Z-BCJG, set the proper ex- 
amination mode by typing in $M, $B, $W, or $A. This mode will re- 
main in force until it is again changed. Then enter any hexadecimal 
address followed by a slash \T\ . 

We have a number of options during the display of memory 

locations. If we want to keep on dis pla ying consecutive locations we 
can do so by entering a down arrow \Jj , as we have seen. If we want 
to display the previous location we can enter an up arrow [£J , as 
shown in this sequence: 



mOOAl 
1009/ 
1008/ 
1007/ 



71 

41 

1 

20 



( n ) 

( ± ) 

( ffl ) 



Regardless of the examination mode, the up arrow \J] displays 
the last byte. This means that use of the up arrow in the mnemonic 
and word modes may be somewhat ambiguous, unless the up arrow is 
simply used for positioning the current location back to a new starting 
point. 

If we want to stop the display of consecutive loc ations at any time we 
can "close" the current location by typing in an | ENTER | , bringing us 
back to the # prompt of Z-BUG: 

#1007/ 20 ( hit | ENTER] ) 

# 

To modify the current memory location ty pe in th e new value in 
hexadecimal, followed by a down arrow [J] or | enter | .jf the examina- 
tion mode is the byte mode, mnemonic mode, or ASCII mode, one or 
two hexadecimal digits can be entered, with any leading hex "A" 
through "F" prefixed by a zero: 

T 



#8001/ 5 


12 


(changes 5 to 12H) 


8002/ 7 


OC 


(changes 7 to 0CH) 


8003/ 0AA 
# 


0BB 


(changes 0AA to 0BBH) 



ENTER 
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If the examination mode is the word mode, up to four hexadecimal 
digits can be entered, with an appropriate leading zero for non- 
numeric digits: 



#8000/ 
8002/ 
8004/ 
8006/ 

# 



B 



0FFFF 1234 (changes FFFF to 1234H) ( 

0FFFF 5678 (changes FFFF to 5678H) ( 

0FFFF 9ABC (changes FFFF to 9ABCH) ( 

0FFFF 0DEFA (changes FFFF to 0DEFAH) [ENTER | 



To modify the current location to an ASCII character while in 
any mode, type in the ASCII character with a leading and trailing 
single quotation mark: 



#8000/ 
8001/ 
8002/ 
8003/ 
8004/ 
8005/ 



S' 



The slash [7] may be used by itself without a location value 
preceding it to reopen the "current" location for any mode. 

Displaying and Modifying 
Memory Locations in Decimal 
and Octal 

EDT ASM-PLUS has the capability to not only display or accept input 
in hexadecimal, but to handle data in decimal or octal. Octal is base 
8 format which is not frequently used on the Z-80, and we will confine 
most of our discussion here to decimal display and input. 

There are two control words that determine the number base used in 
type outs and inputs. The command "$0" sets the Output radix 
(number base) control word to 8, 10, or 16. The command "$l" sets 
the Input radix to any radix between 2 and 16. 

The format of the $0 command is 

(radix)$0 
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where radix is 8, 10, or 16. The default radix is 16, and this is the output 
format when Z-BCIG is initially entered. The radix may be changed at 
any time by entering the $0 command. 

To see how this works, look at the following sequence, which first prints 
several locations in hexadecimal, and then prints the same locations in 
decimal and octal. 



#16$0 




#1000/ 


20 


1000/ 


28 


1002/ 


7 


#10$O 




#1000/ 


32T 


4097T/ 


40T 


4098TV 


71 


#8$0 




1000/ 


40Q 


10001 CV 


50Q 


100020/ 


7Q 



( enter 
( enter , , 
( | ENTER] ) 

( enter [T] ) 
( enter \J] ) 
( [ enter] ) 



( enter 
[ enter 



ffl 



ENTER [ ) 



The suffix of "T" denotes a decimal number as we can see above, 
while a "Q" is used to represent an octal number. 

It is important to note that the input radix remains hexadecimal while 
the output radix is changed. The input and output radices are com- 
pletely separate and set by two different commands. Of course, in 
most cases the two will be the same radix to avoid confusion. 
The format of the $1 command is 
(radix)$I 

where radix is any number from 2 through 16. The default radix is 16, 
and this is the format when Z-BCIG is initially entered. The radix may 
be changed at any time by the $1 command. 

The following sequence sets both the input and output radix to 
decimal and then modifies the decimal locations to the values shown. 
Note that the "T" suffix is used after every display of a decimal 
number. 
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#10$l 








#10$O 








#32000T/ 


255T 


123 


(change 255 to 123) ( 


32001T/ 


255T 


156 


(change 255 to 156) ( 


32002T/ 


255T 


189 


(change 255 to 189) ( 


32003T/ 
# 


250T 


111 


(change 250 to 111) ( 



1_ 



ENTER J ) 



Although the input radix can be any number from 2 through 16, most 
input operations we would typically want to perform would be either 
decimal, for table data, or hexadecimal, for instruction data. Occa- 
sionally it might be useful to enter data in binary when bit processing is 
involved. Entering data in base 7 or 13 would probably have somewhat 
more limited applications. 

The suffixes of "T" for decimal, "H" for hexadecimal, and "O" or "Q" for 
octal may be used anytime data is entered, regardless of the input radix 
setting. If we are in the hexadecimal input mode (16$1), for example, we 
can enter hexadecimal data by typing hexadecimal digits (with a leading 
zero for non-numeric), decimal data by typing decimal digits with a "T" 
suffix, or octal data by typing octal digits with a "Q" suffix: 



#16$0 

#16$l 

#8000/ 

8001/ 

8002/ 

8003/ 

8004/ 



12 

OFF 

15 

0A5 

32 



0AA 

12 

12T 

99T 

77Q 



(change to 0AAH) ( \U ) 
(change to 12H) ( Q] ) 
(change to 12 
decimal) ( Q] ) 

(change to 99 
decimal) ( [Q ) 

(change to 77 oc- 
tal) 



( I ENTER 1 



The slash \J\ may be used at any time to reopen the "current" location. 
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Symbolic Debugging 



EDTASM-PLGS permits another way of entering or displaying data. If 
an in-memory assembly has been run and Z-BGG is entered, then we 
may choose to make symbolic references. In this mode of opera- 
tion, we can refer to locations in the in-memory object code by their 
labels instead of by reference to absolute locations. 

This is a very powerful feature of EDTASM-PLGS, made possible by 
the fact that the symbol table is resident in memory at the same time 
as the object code and debugger. 

Let us investigate how this type of reference functions. We will use the 
same program we used in an earlier chapter on in-memory assembly. 



71 AD 21003C 


00110 CLEAR 


LD 


HL,3C00H 


;ADDRESS OF 
SCREEN START 


71 B0 010004 


00120 


LD 


BC.1024 


;COUNT OF POSI- 
TIONS 


71B3 3E20 


00130 LOOP 


LD 


A,20H 


;LOAD BLANK 


71B5 77 


00140 


LD 


(HL),A 


;STORE BLANK 


71B6 23 


00150 


INC 


HL 


;BUMP POINTER 


71 B7 0B 


00160 


DEC 


BC 


DECREMENT 
COUNT 


71B8 78 


00170 


LD 


A,B 


;TEST DONE 


71 B9 B1 


00180 


OR 


C 


;MERGE LS BYTE 


71BA20F7 


00190 


JR 


NZ,LOOP 


;GO IF MORE TO 
STORE 


0000 


00200 


END 






00000 


TOTAL ERRORS 






CLEAR 


71AD 








LOOP 


71 B3 









NOTE: Some lines which fit as one line on your 
computer screen will not fit on this manual page as 
one line. These lines have been continued on a se- 
cond line with the information continued beneath 
the last column. 

This program has two labels, "CLEAR" and "LOOP". The instructions 
corresponding to the two labels are at 71ADH and 71B3H, respective- 
ly (these addresses may vary dependent upon the version of 
EDTASM-PLGS in use). 
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The symbolic debugging mode is set by the Z-BCJG command "$S". It 
is also the default (initial) mode. To get back to the numeric mode, a 
second command, "$N", is used. When the numeric mode is in force, 
all data will be displayed as in the previous examples. 

- If we have assembled the program above in memory (A/IM), then we 
can set the symbolic mode and reference locations by their symbolic 
names: 



#$S 

#$B 
#CLEAR/ 
CLEAR +1/ 
CLEAR + 2/ 
CLEAR +3/ 
CLEAR +4/ 
CLEAR +5/ 
LOOP/ 
LOOP + 1/ 
LOOP + 2/ 
LOOP + 3/ 
# 



21 



3C 

1 



4 

3E 

20 

77 

23 



HI 



ENTER 



Initially we typed in the "CLEAR"; for every following location Z-BUG 
supplied the proper symbolic name of the location. 

Note that Z-BCJG references every location to the last symbol if no new 
label is found. When a new label is found, consecutive locations are 
referenced to the new label. 

Of course, we can use the symbolic mode with any examination 
mode; they are two separate functions: 



) 



We can also enter expressions that include symbolic terms at any 
time. For example if we were in the word examination mode we 
could alter location LOOP+ 10 (out of the program) to a 16-bit ad- 
dress of LOOP + 4! 



#$s 








#$M 






#CLEAR/ 


LD HL,3C00 


( 


t 


CLEAR + 3/ 


LD BC 5 400 


( 


LOOP/ 


LD A,20 







#$w 
#$s 

#LOOP + 10/ 
#LOOP + 10/ 
#$N 

#71B3+10/ 
LOOP 



LOOP + 4 ( I ENTER 

LOOP + 4 ( | ENTER 



71 B7 



In the sequence above, we first set word mode ($W) and symbolic 
mode ($S). We then examined location LOOP + 10H and modified the 
location with the value of LOOP + 4. When we again examined 
LOOP + 10 it had the value of LOOP + 4 in it. In numeric format ($N) 
LOOP is equal to 71B3, and LOOP + 4 is 71B7. 

In processing the above, Z-BUG looked up the symbol LOOP in the 
symbol table to try to resolve every input reference using it. In the 
symbolic mode, Z-BUG also prints out every output in terms of values 
in the symbol table, if it finds a symbol in the approximate range of 
the value involved. If no symbol is in the approximate range, Z-BUG 
reverts back to output of values in whatever numeric radix is in effect. 

Any operator normally used for assemblies may be used in an expres- 
sion, except that ".DIV." must be used for divide as T is used to open 
a location for display. 

The use of "$" to indicate the current location (as in the 

Assembler) is not recommended as it may be confused with an 
ESCAPE. Use a period (".") instead. 

Z-BUG has an expression evaluator command, " = ", that allows a 
calculator-style typeout of all types of expressions. Normally it can be 
used to find the locations of a symbol plus or minus a displacement, 
but the command may be used for any expression, including those for 
hexadecimal arithmetic. Some examples are shown here: 

#5 + 0EF = 0F4 

#TABLE + 200 = 71B5 

#8014-15E = 7EB6 

#4AA+ 10T+377Q = 5B3 
Symbolic debugging can be used with great convenience in examin- 
ing and modifying tables of data, variables, and constants, and in us- 
ing some of the other Z-BUG commands we will be discussing shortly. 
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Free Ose of Symbols, 
Expressions and Constants 

Z-BOG is extremely flexible in allowing use of symbols at any 
time, regardless of input or output mode. A non-numeric string that 
is input to open a location or to modify a location will cause Z-BGG to 
scan the current symbol table (if any) to find an equivalent value for 
the string. 

Likewise, any expression may be used to open or modify locations. 
The expressions may contain symbols, constants, and operators in any 
combination. 

Suffixes may be used after numeric data for opening or modifying a 
location regardless of the input radix. Suffixes may also be used in ex- 
pressions in any combination. Of course, no suffix is necessary for in- 
putting data in the current input radix. 



Displaying a Block 
of Locations 

A block of locations may easily be displayed in Z-BGG by using the 
$T command. The format of $T is 



(first address) I6(last address)$T 



where b is a blank 



This command will Type out the block from first address through last 
address in whatever examination mode and output radix has been 
specified. 





#1000 100E$T 






1000/ 




20 




1001/ 




28 


1002/ 




7 


1003/ 




78 


1004/ 




0B9 


1005/ 




0E 


1006/ 




2A 


1007/ 




20 


1008/ 




i 


1009/ 




41 


100 A/ 




71 


100B/ 




0D7 


100C/ 




28 


100D/ 




14 


100E/ 




0FE 




# 


[@I 




The | SHIFT | 


or | BREAK | 




the T command. 





may be used to hold or abort output for 
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Displaying and Modifying 
Registers and Flags 

The $R command of Z-BUG causes a display of ail registers, except 
the R register, in hexadecimal. (The R register changes its value with 
each new instruction for memory refresh and examining its contents is 
somewhat meaningless.) 

The format of the register display is 



#$R 
A=XX F=XX= B=XX C=XX D =XX E =XX H =XX L =XX 

A' = XX P=XX= B' = XX C' = XX D' = XX E'=XX H' = XX L' = XX 

SP = XXXX PC = XXXX IX = XXXX 1Y = XXXX l = XX 
# 
Individual registers or register pairs can also be examined and 
modified by entering the register or register pair name followed by the 
"open" symbol, " / ". 

#A/ 255T 

#HU 30000T 

The register or register pair names follow standard Z-80 mnemonics 
— A, B, C, D, H, L, BC, DE, HL, SP, PC, IX, IY, or I, or their primed 
equivalents. 

It is not recommended that the PC or SP registers be modified 
by the user. The PC is used to hold the address of the current instruc- 
tion of the user's program for G(o) and single-step commands and 
changing the PC during debugging may be disastrous. The SP points 
to the user's stack area and changing the SP may be equally bad. 

Registers can be examined after a breakpoint in an object program 
to see that they hold expected results. They may be modified before 
continuing from a breakpoint or single step or before transferring 
control back to an object program routine. We will show some ex- 
amples of this action later in the chapter. 

Flags may be examined by typing F/ or by using the $R command. 
The format of the flags printout is 

= SZHP/VNC 

if the individual flags are set they will be listed; if the individual flags 
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are reset they will not be listed. The display 

= SP/V 

for example, indicates that the S and PA/ flags = 1 and that Z, H, N, 
and C = 0. 



One Time Type Outs and 
Examining the Addressed 
Location 

There are four additional Z-BCIG commands that are used during ex- 
amination of memory, the ";'' command, the " = " command, the right 
cursor Q command, and the ":" command. 

The ";" command is used after the Z-BGG prompt or after displaying 
a location with a slash. It forces the contents of the current location to 
be displayed in numeric mode and would typically be used to temp- 
orarily display the numeric value of a location while in the symbolic 
mode. 

If we were in mnemonic mode ($M), for example, we would be dis- 
playing instruction mnemonics. If we also were in symbolic mode 
($S), we would be displaying the instructions with symbolic addresses 
rather than absolute addresses. In the case of our previous program 
example, a display of the instruction at 71 BAH would result in: 

#$M 
#$S 
#71 BA/ JR NZ,LOOP 

If we wanted to find out the equivalent absolute address for "LOOP" 
we could immediately enter a ";" after the mnemonic typeout to ob- 
tain 

#71 BA/ JR NZ,LOOP; JR 71 B3 

The " = " command is used in similar fashion, either after a "#" to 
display the current location or after display caused by a slash. It 
displays the current location in byte examination mode ($B) and 
numeric mode ($N) regardless of the current examination and 
numeric/symbolic mode. 
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The " = " command would typically be used when we were confused 
about the contents of a location displayed in mnemonic or symbolic 
form. This could easily happen if we were in mnemonic examination 
mode and we started displaying data from a table, for example. The 
data might well be converted to equivalent instructions, and we could 
print out the data in numeric form by entering the " = " command. 

#8000/ RST38 =0FF 

The Q command is used to open a new location based on the 
addressed location in the current instruction (mnemonic mode) or 
the address represented by the current location and the current 
location plus one. 

It is convenient to be able to perform this action for a number of 
reasons. In the case of instructions that reference memory locations, 
the Q can be used to examine the contents of the locations that are 
being loaded or used for storage or to follow the sequence of 
instructions for instructions that jump to other locations. When in 
byte, word, or ASCII mode, the Q may be used to examine the 
location pointed to by the address found in the two current bytes; this 
is handy for examining routines or data pointed to by tables of 
addresses. 

Suppose that we are in mnemonic mode and are examining an 
instruction that loads a variable "COUNT". We can examine the 
contents of COUNT by entering a right arrow after the mnemonic 
print out: 



#STARTV 
COUNT/ 



LD ACCOUNT) 
LD HL.OFFFF 



= 21 



(H 



In the sequence above, START was examined in mnemonic mode. 
The instruction at START referenced COUNT, and by typing Q 
location COUNT was opened and printed out in mnemonic form. We 
then converted the mnemonic form into numeric form by " = ", which 
printed the first byte, or the contents of COUNT. As another example, 
suppose that we had been in word examination mode and 
investigating a table of subroutine addresses. We could open the 
location corresponding to any of the addresses by using : 

( H ) 



#TABLB 


70FC 


70FC/ 


203E 


#$M 




#/ 




70FC/ 


LD A 



100 



The " : " command is used to display the current location in flags mode 
format ( = SZHP/VNC). This command would normally be used to ex- 
amine a byte representing Z-80 flags, such as stack data created by 
PUSH AF. y 



Breakpointing 



A breakpoint is very similar to a STOP command in BASIC; it is a 
way of breaking out of program execution at a predetermined point in 
the program. 

The breakpoint is invaluable during program debugging because: 

1. It informs us that we reached the breakpoint 

2. It allows us to examine intermediate results in 
registers or memory. 

Let us see how breakpointing can be used with Z-BUQ. We will use the 
program we have been working with in this chapter and the chapter 
on in memory assembly: 



71AD21003C 00100 CLEAR LD HL3C00H 



71 B0 010004 

71B3 3E20 
71 B5 77 
71B6 23 
71B7 0B 

71B8 78 
71 B9 B1 
71 BA 20F7 

0000 



00110 

00120 LOOP 
00130 
00140 
00150 

00160 
00170 
00180 

00190 



LD BC,1024 



LD 
LD 
INC 



A,20H 
(HL),A 
HL 



DEC BC 



LD 
OR 
JR 

END 



A,B 

C 

NZLOOP 



;ADDRESS OF 

SCREEN START 
;COUNT OF POSI- 
TIONS 
;LOAD BLANK 
;STORE BLANK 
BUMP POINTER 
DECREMENT 

COUNT 
;TEST DONE 
;MERGE LS BYTE 
;GO IF MORE TO 
STORE 



00000 TOTAL ERRORS 
CLEAR 71 AD 
LOOP 71 B3 

NOTE: Some lines which fit as one line on your 
computer screen will not fit on this manual page as 
one line. These lines have been continued on a 
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second line with the information continued beneath 
the last column. 

We would like to execute the program to see if it actually does clear the 
screen. We will put in a breakpoint at LOOP so that we can check the 
registers (we have never learned to completely trust computers. . .). 

Z-BUG allows up to eight separate breakpoints, numbered through 7. 
The format of the command to set a breakpoint is: 

(address)$X 

The address value can be a symbolic address, a numeric address, or a 
symbolic expression. We could, for example, use 

#LOOP$X or #71B3$X or #CLEAR + 6$X 

Z-BGG uses the next available breakpoint number. Since no other 
breakpoints are in force at this point, Z-BGG uses breakpoint number 
0. We can display all breakpoints used at any time by the com- 
mand $D: 

#LOOP$X 
#$D 
@ LOOP 

The display above tells us that one breakpoint is in effect @ LOOP, 
and that the number of the breakpoint is 0. 

Now we are ready to execute the program. We can execute from any 
address by using the $G command of Z-BUG. The format of the $G 
command is 

(address)$G 
Here again the address may be symbolic, numeric, or an expression. 
We will execute starting at CLEAR: 

#CLEAR$G 
BRK @ LOOP 

# 
The $G command caused program execution starting at CLEAR. The 
two instructions at CLEAR and CLEAR + 3 were executed, and a 
breakpoint then occurred at LOOP before execution of the instruc- 
tion at LOOP. 



At this point we can perform any operations that we think miqht be 
useful, including examining registers or memory, changing registers 
or memory, or setting additional breakpoints. We will display the 
registers to allay some of our fears about computers: 

#$W 

#HL7 3C00 

#BC/ 400 

# 

After making any examinations that we desire, we can then C(ontinue) 
from the current breakpoint by the $C command. The format of the 
$C command is: 

(continue count)$C where (continue count) is interpreted as 
decimal 

The continue count tells Z-BUG not to stop at the current breakpoint 
until the current breakpoint has been reached the number of times 
equal to the count. If no count is used, a default value of 1 is assum- 

f^Ao WG c ° n L tinued by $C ' we would execute the instruction at 

LOOP, and then continue execution of the program. The program in 
this case brings us back to the breakpoint at LOOP 
#$C 
BRK ©LOOP 

# 

Wejrould stop at the 500th time through the loop by 500$C as shown 

#500$C 
BRK ©LOOP 
#BC/ 20B 

# 

The count in BC has been decremented down to 523 at this point 
(notice that the upper portion of the screen has been cleared). 
Before we continue, we had better put in a breakpoint at the end of 
the program to guarantee our return to Z-BCJG. If this is not done we 

vILTTw'T",^ 01 - The laSt inst ™tion of the program is at 
71 BAH. We should like to breakpoint at the last instruction plus one 
instruction. Although there is no instruction there (there is gar- 
bage of some type), we can breakpoint at 71BC anyway and simulate 
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the non-existent instruction. 

#71BC$X 
#$D 

@ LOOP 

1 @ LOOP + 9 

# 

At this point there is probably no need for the breakpoint at LOOP. We 
can delete it by another Z-BCIG breakpoint instruction, $Y(ank). The $Y 
can be used to yank all breakpoints by entering: 

#$Y 

We can also selectively yank or delete breakpoints by specifying a 
breakpoint number for deletion: 

#0$Y 

The command above deletes the breakpoint at LOOP, number 0. When 
a breakpoint is yanked, it is released to the pool of eight possible break- 
points and could immediately be used again. The number specified 
before the $Y is always interpreted as a decimal number. 

We now have one breakpoint, at LOOP + 9: 

#$D 
1 @ LOOP + 9 

# 

If we continue from this point, we will go through the remainder of the 
loop, clearing the screen and finally "fall through" to the breakpoint at 
LOOP + 9. At that point we can delete the breakpoint and continue fur- 
ther debugging, if necessary. 



#$C 

1 BRKi 
#$Y 
# 



LOOP+9 



Op to 8 breakpoints can be used in the fashion above to generally cover 
all paths through the program for debugging. The combination of 
multiple breakpoints and "continue for n times" is a powerful debugg- 
ing tool that should let the user have complete control over program 
checkout. 



Single Stepping Through a Program 

Z-BCJG also provides the capability to single-step through a program. 
In this mode, one instruction at a time is executed with a display of 
the next instruction to be executed and the contents of that location. 
The format of the single step command is 
(address)© 

To initially start the single step sequence, a numeric or symbolic ad- 
dress can be specified as in: 

#CLEAR@ 
CLEAR + 3/ LD BC,400 

# 

Thereafter only the "(< 
quential instructions: 



)" is necessary to continue stepping through se- 



#CLEAR@ 

CLEAR + 3/ LD BC,400 
#@ 

LOOP/ LD A,20 

m 



LOOP + 2/ LD(HL),A 

At any time after the display of the current instruction, other Z-BUG 
commands may be used, such as commands to examine registers and 
memory locations. Single stepping may thus be used to trace the 
flow of the program and the contents of registers and memory loca- 



tions. 



Single stepping may be used after a breakpoint. ESCAPE "C" 
without a continue count can be used to resume program ex- 
ecution after single stepping. 
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Loading and Saving System 
Format Tapes 

Z-BOG has the capability of saving any RAM memory area on 
cassette tape under a file name in "SYSTEM" format. A tape file 
created in the $P(unch) command may be reloaded by either the 
Z-BUG $L(oad) command or by the SYSTEM command in Level II 
BASIC. 

The $P command can be used to save "patched" (partially debug- 
ged) assembly-language programs, several programs that have been 
merged into one file, data areas, or any other convenient set of 
instructions or data or both. 
The format of the $P command is 

(first) b(last) ^execution) 16NAME$P where 16 is blank 

First is the first memory location to be saved, last is the last memory 
location to be saved, execution is the starting address (if any), and 
NAME is a 1 to 6 character file name. If NAME is omitted, the name 
"NONAME" is used. 

After the $P string has been entered, Z-BOG displays the message 
"READY CASSETTE". When the cassette is positioned, any key can be 
pressed and the block of locations from first to last is written to 
cassette. 

If no execution address is required, simply type in a "dummy" 
address for the above sequence. 
To reload the saved file under Z-BUG enter 
#NAME$L 

If no file name is used, Z-BCJG will reload the next cassette file into 

memory. After the load, the Z-BOG prompt character "#" will be 

displayed. 

The starting address on the tape is loaded into the user PC register 

(examine it by "PC/"). 

If a checksum error occurs during the load, a "C" will be displayed in 
place of the "tape load" asterisk; if a memory verify fails, an "M" will 
be displayed. In either failure case, the tape will continue the load un- 
til the end of the cassette file. 



Z-BOG will skip over files that do not have the correct file name. 
Previous problems in certain TRS-80 software relating to tape searches 
for named files are not present in EDTASM-PLOS, and more than one 
named file may be stored on cassette (and also retrieved). 
Z-BOG uses the same format for cassette files as Level II BASIC 
SYSTEM mode, so Uhs P(unched) under Z-BOG can be loaded under 
Level II BASIC by: 



> SYSTEM 

*?NAME 

*?/ 



(enter SYSTEM mode) 
(read cassette file) 
(transfer to "execution" address) 
EDTASM-PLOS object files created by the EDTASM-PLOS 
Assembler may also be loaded by the Z-BOG L command. 

Loading Stand-Alone Z-BOG 

Z-BOG may be loaded alone, without the Editor and Assembler, to 
provide more room for large assembly-language programs that are to 
be debugged. 

To load Z-BOG in this "stand-alone" fashion, position the EDTASM- 
PLOS cassette tape directly before the Z-BUG file (SIDE TWO) and 
load using the SYSTEM command: 

>SYSTEM (enter SYSTEM mode) 

*?ZBUG (load Z-BCJG) 

* II (start execution) 

The MICROSOFT COPYRIGHT notice, followed by "STAND-ALONE 
Z-BUG" will be displayed, followed by the Z-BOG prompt character "# M . 
Normal Z-BCJG (not Editor or Assembler!) operations can now be car- 
ried out. 

Stand-Alone Z-BOG occupies about 7K bytes of RAM with the 
user RAM area starting at about 5BS0H. Do not attempt to use 
RAM memory below 5B80H. 
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Z-BOG Cautions and 
Error Messages 

Z-BCJG utilizes ReSTart (RST) instructions as either calls to ROM 
routines or breakpoint control, and therefore RSTs cannot be used 
in user programs that are run under Z-BCJG. 

When a user executes a program under Z-BCJG, an internal (to Z-BGG) 
stack is utilized as a user stack. This stack area is approximately 50 
bytes long and will suffice for most user programs. If the user s pro- 
gram contains many levels of stack use, however, he should set up his 
own stack area in the user RAM by performing an 

LD SP.TOPSTK 

where "TOPSTK" is a user-defined "top-of-stack" address. This top of 
stack will usually be the maximum memory location available plus 
one, but may be any high memory area away from the object code. 

Z-BOG error messages include "BAD EXPRESSION", "BAD MEMORY", 
"DIVISION BY 0", "STACK OVERFLOW", and "UNDEFINED SYMBOL" with 
the same meanings as the corresponding Assembler messages. 

The "ZERR" message is also used to denote one of the following 
conditions: 

1. Expression followed by semicolon instead of an equal 
sign. 

2. Illegal ESCAPE command character. 

3. Internal breakpoint problem. 

4. Illegal input or output radix specification. 

5. Attempting to set more than eight breakpoints. 

6. Attempting to set a breakpoint at a location where one 
already exists. 

7. Attempting to breakpoint a register or register pair. 

8. Attempting to breakpoint an RST instruction. 

9. Specifying a continue count ($C) of 0. 

10. Attempting to continue ($C) without being in a break- 
pointed condition. 
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General Index 

#$YM labels 76> 77 

Absolute assemblies 55 

Absolute origin 55 

"Addressed" location display 100 

AND, logical 57 

ASCII mode, Z-BC1G ........... .... ......'. 88 

Assembler expression evaluation 56-59 

Assembler operation 42-45 

Assembler switches 49 50 

Assembling into memory 50-54 

Assembly listing 44 

Automatic extend, editor command 36 

Automatic origin 50-52 

Block, display 97 

Breakpointing 101-104 

Byte mode, Z-BOG '.'.'.'* 87 

Cassette spike 12 

Cassette format for EDTASM-PLCJS '.'. '. . ',, . .. '. ' 1 1 

Change, Editor subcommand 25 

Collective edit 31 

Commands, Editor 18-23 

Conditional assembly 59-61 

Copy, Editor command 32 

Cross assembler 7] 

DEFB, pseudo-op 46 

DEFL, pseudo-op 45 

DEFM, pseudo-op 46 

DEFS, pseudo-op 47 

DEFW, pseudo-op 46 

Deletions, character 25 

Display, addressed location 100 

Displaying a block 97 

Displaying memory 87-92 
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Displaying registers 98 

Editor commands 18-23 

END, pseudo-op 45 

ENDM 72 

EQ(J, pseudo-op 47, 48 

Equals operator 58 

Error messages, Editor 39 

Error messages, Assembler 83, 84 

Error messages, Z-BCJG 108 

Examples, macros 78-80 

Expression evaluation 95 

Extend, Editor subcommand 26 

Fields 42 

Find, Editor command 21, 22 

Free-form fields 43 

Hack, Editor subcommand 26 

Hardcopy, Editor command 19 

Hardware for' system 11 

Input number base, Z-BGG 91 

Insert, Editor command 18, 20 

Insert, Editor subcommand 25 

Insertions, character 25 

Kill, Editor subcommand 26 

Label column 42 

Label, in macros 76 

Left arrow, Editor subcommand 24 

Line, Editor subcommand 26 

Line number offsets 30 

Load, Editor command 19 

Loading EDTASM-PLOS from cassette 12 

Loading problems 13 

Loading Stand-Alone Z-BGG 107 

Loading System Tapes 106 

Logical Operators 57, 58 

Macro definition 64-67, 72-73 
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Macro examples 78-80 

Macro name 65, 72 

Macro reference 74 75 

Macro use 70 71 

Macros 64 80 

Macros for subroutine calls 78 

Manual origin 53, 54 

Memory, displaying 87-92 

Memory modifying 87-92 

Microsoft 10 

MUST command 76 

Modifying memory 87-92 

Modifying registers 98 

Modulo operator 58 

Move, Editor command 31 

Nested macros 72-73 

Not equals operator 58 

NOT operator 57 

Number, Editor command 20 

Object code 45 

Offsets, line number 30 

One time typeouts 99-101 

Operands 42 

Operation code 42 

OR, logical 57 

ORG pseudo-op 45, 46 

Output number base, Z-BUG 90-91 

Parameters, in macros 67-69, 74-75 

Positioning commands, Editor 21, 22 

Precedence, operators 59 

Print, Editor command 19 

Pseudo operations 45 48 

Quash command 37, 38 

Ranges of lines 29 
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Registers, displaying 98-99 

Registers, modifying 98-99 

Relocatable programs 45, 46 

Remarks column 42 

Replace, Editor command 20, 21 

RESET recovery procedure 15 

Saving SYSTEM tapes 106 

Search, Editor subcommand 25 

Shift operator 57 

Single stepping 105 

Source lines 42 

Subcommands, Editor 24-28 

Subroutine calls with macros 78 

Substitute, Editor command 34, 35 

Suppressing listing of macros 76 

Switches, assembler 49, 50 

Symbol table 47, 48 

Symbol table codes 81-82 

Symbolic debugging 93-95 

Symbolic form 43 

Symbolic mode 93-95 

Word mode, Z-BC1G 88 

Write, Editor command 19 

XOR, logical 57 

Z-BUG 86-108 

Z-BOG cautions 108 

Z-BCJG operation 86 

Z-BUG, Stand-Alone 107 
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